---
title: "Metric Image API — KPI stat tile images via API | Imejis"
description: "Turn KPIs into stat tile images — a big formatted number, label and up/down delta badge — refreshed on every API call. Start generating KPI images free."
url: "https://www.imejis.io/components/metric"
---

# Metric Image API — KPI stat tile images via API | Imejis

A stat tile: one big formatted number with an optional label and up/down delta badge — built for KPIs, revenue counters and scorecards.

## Use cases

- Daily revenue or signup tiles posted to Slack
- OG images with live user or star counts
- Investor update graphics with growth deltas
- Follower milestone cards for social media

## Properties

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| string` | — | The headline value to display. |
| `label` | `string` | `""` | Caption describing the metric. |
| `labelPosition` | `'top' \| 'bottom'` | `"top"` | Whether the label sits above or below the value. |
| `format` | `'number' \| 'compact' \| 'percent' \| 'currency' \| 'none'` | `"number"` | How the value is formatted (48,250 / 48.3K / 48% / $48,250 / raw). |
| `currencySymbol` | `string` | `"$"` | Currency symbol used with the 'currency' format. |
| `prefix` | `string` | — | Text prepended to the value. |
| `suffix` | `string` | — | Text appended to the value. |
| `delta` | `number` | — | Change amount shown in the delta badge (no badge when unset). |
| `showDelta` | `boolean` | — | Show the delta badge. |
| `deltaFormat` | `'percent' \| 'value'` | `"percent"` | Whether the delta renders as a percentage or a raw value. |
| `deltaDirection` | `'up-good' \| 'down-good'` | `"up-good"` | Which direction counts as positive (colors the badge). |
| `align` | `'left' \| 'center' \| 'right'` | `"left"` | Horizontal alignment of the tile content. |
| `valueSize` | `number` (min 0) | `0` | Font size of the value in pixels. |
| `valueColor` | `color` | `"#0f172a"` | Color of the value. |
| `labelColor` | `color` | `"#64748b"` | Color of the label. |
| `deltaUpColor` | `color` | `"#16a34a"` | Badge color for a positive delta. |
| `deltaDownColor` | `color` | `"#dc2626"` | Badge color for a negative delta. |
| `opacity` | `number` | `1` | Overall component opacity from 0 (transparent) to 1 (opaque). |
| `borderWidth` | `number` | `0` | Border thickness in pixels around the component. |
| `borderColor` | `color` | `"transparent"` | Border color (any CSS color). |
| `borderStyle` | `'solid' \| 'dashed' \| 'dotted' \| 'double' \| 'none'` | `"solid"` | Border line style. |
| `borderRadius` | `number` | `0` | Corner radius in pixels. |
| `boxShadow` | `string` | — | CSS box-shadow applied to the component, e.g. "0 4px 6px rgba(0,0,0,0.1)". |

## Sample design JSON

```json
{
  "title": "Metric sample",
  "description": "A dynamic KPI tile",
  "dimensions": {
    "width": 800,
    "height": 420
  },
  "background": {
    "color": "#ffffff"
  },
  "components": [
    {
      "id": "sample-metric",
      "key": "revenue",
      "type": "metric",
      "position": {
        "x": 250,
        "y": 140
      },
      "rotation": 0,
      "size": {
        "width": 300,
        "height": 140
      },
      "dynamic": true,
      "properties": {
        "value": 48250,
        "label": "Revenue",
        "format": "currency",
        "labelPosition": "top",
        "delta": 12.5,
        "showDelta": true,
        "deltaFormat": "percent",
        "deltaDirection": "up-good",
        "align": "center",
        "opacity": 1
      }
    }
  ]
}
```

## Examples

### Daily signups tile

New signups today with a green up-delta — ready for a morning Slack post.

API overrides that reproduce this example:

```json
{
  "revenue.value": 1382,
  "revenue.label": "Signups today",
  "revenue.format": "number",
  "revenue.delta": 4.6
}
```

### Conversion rate scorecard

Checkout conversion as a percentage, with the delta shown in raw points.

API overrides that reproduce this example:

```json
{
  "revenue.value": 3.8,
  "revenue.label": "Checkout conversion",
  "revenue.format": "percent",
  "revenue.delta": 0.4,
  "revenue.deltaFormat": "value"
}
```

## API overrides

Push the latest number with '<key>.value' (or just '<key>') and the change with '<key>.delta'; label and format are overridable too.

Flat override payload (`key.property` addressing) with the sample design's current values — send only the keys you want to change:

```json
{
  "revenue.value": 48250,
  "revenue.label": "Revenue",
  "revenue.format": "currency",
  "revenue.labelPosition": "top",
  "revenue.delta": 12.5,
  "revenue.showDelta": true,
  "revenue.deltaFormat": "percent",
  "revenue.deltaDirection": "up-good",
  "revenue.align": "center",
  "revenue.opacity": 1
}
```

```bash
curl --location 'https://render.imejis.io/v1/{{YOUR_DESIGN_ID}}' \
--header 'dma-api-key: {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "revenue.value": 48250,
    "revenue.label": "Revenue",
    "revenue.format": "currency",
    "revenue.labelPosition": "top",
    "revenue.delta": 12.5,
    "revenue.showDelta": true,
    "revenue.deltaFormat": "percent",
    "revenue.deltaDirection": "up-good",
    "revenue.align": "center",
    "revenue.opacity": 1
}'
```

`{{YOUR_DESIGN_ID}}` and `{{YOUR_API_KEY}}` are placeholders: first create
the design in your account (paste the sample design JSON above into the
editor at https://app.imejis.io, or create it programmatically via the
imejis MCP server's `create_design` + `update_design` tools), then render
it with the design's id and one of your API keys.

Agents: the MCP server at https://api.imejis.io/api/mcp exposes this same
catalog as structured data via the `list_component_types` tool (property
kinds, allowed values, bounds, ready-to-use sample designs).

## Frequently Asked Questions

### Can the number update on every API call?

Yes — send '<key>.value' (or just the key) plus '<key>.delta' for the change badge; the label and format are overridable too.

### How are values formatted?

format supports number (48,250), compact (48.3K), percent, currency with a custom currencySymbol, or none for raw text — plus prefix and suffix strings.

### How does the delta badge decide its color?

deltaDirection sets which way is positive: 'up-good' colors increases as positive, 'down-good' does the opposite (useful for costs); both colors are customizable.

### Can the value be text rather than a number?

Yes — value accepts a string too; combine format 'none' with prefix or suffix when you need units like '1,284 users'.

## Variants

- [Compact](https://www.imejis.io/components/metric/compact.md) — Large numbers abbreviated (48.3K) — dashboards and social cards.
- [Negative delta](https://www.imejis.io/components/metric/negative-delta.md) — A drop against an up-is-good metric renders the badge in the down color.
- [Suffix units](https://www.imejis.io/components/metric/suffix-units.md) — Raw value with a custom suffix instead of built-in formatting.
- [Currency](https://www.imejis.io/components/metric/currency.md) — A revenue counter formatted as money with a growth delta badge.

All components: https://www.imejis.io/components.md