> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/metric.md).

# The metric object

The metric object in the Shortcut API - every field, an example, and the endpoints that return it.

A business number from the Reports pages.

## Fields

| Field                   | Type                                                      | Description                                                                                                                                                              |
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `object`                | `"metric"`                                                | Always `metric`.                                                                                                                                                         |
| `metric`                | string                                                    | The metric's id.                                                                                                                                                         |
| `name`                  | string                                                    | Its name on the Reports pages.                                                                                                                                           |
| `unit`                  | `money`, `count`, `percent`, `days`, `minutes`, `hours`   | Money is US dollars; percent is a share from 0 to 1.                                                                                                                     |
| `definition`            | string                                                    | What it counts, in a sentence.                                                                                                                                           |
| `status`                | `ok`, `not_enough`, `not_ready`, `no_data`, `not_allowed` | `ok`: `value` is the number. `not_enough` / `not_ready`: too little data yet. `no_data`: nothing in the window. `not_allowed`: margin numbers, which tokens cannot read. |
| `value`                 | number or null                                            | The number, when `status` is `ok`. Quote it as given; never add up or average metrics yourself.                                                                          |
| `period`                | object                                                    | The window a metric covers.                                                                                                                                              |
| `period.from`           | string                                                    | The first day covered, `YYYY-MM-DD` in the workspace's timezone.                                                                                                         |
| `period.to`             | string                                                    | The last day covered, included.                                                                                                                                          |
| `period.label`          | string                                                    | How the Reports page labels the window.                                                                                                                                  |
| `previous`              | object or null                                            | The comparison, when `compare` was asked.                                                                                                                                |
| `previous.value`        | number or null                                            | The comparison window's number.                                                                                                                                          |
| `previous.label`        | string                                                    | Its label.                                                                                                                                                               |
| `usual`                 | object                                                    |                                                                                                                                                                          |
| `usual.status`          | `ok`, `insufficient_data`                                 |                                                                                                                                                                          |
| `usual.lower`           | number or null                                            |                                                                                                                                                                          |
| `usual.upper`           | number or null                                            |                                                                                                                                                                          |
| `usual.sampleCount`     | integer                                                   |                                                                                                                                                                          |
| `usual.required`        | `12`                                                      |                                                                                                                                                                          |
| `usual.method`          | `"linear_p10_p90"`                                        |                                                                                                                                                                          |
| `usual.windows`         | array of objects                                          |                                                                                                                                                                          |
| `usual.windows[].from`  | string                                                    |                                                                                                                                                                          |
| `usual.windows[].to`    | string                                                    |                                                                                                                                                                          |
| `usual.windows[].value` | number or null                                            |                                                                                                                                                                          |
| `components`            | array of objects                                          |                                                                                                                                                                          |
| `components[].key`      | string                                                    |                                                                                                                                                                          |
| `components[].label`    | string                                                    |                                                                                                                                                                          |
| `components[].status`   | `available`, `partial`, `unavailable`                     |                                                                                                                                                                          |
| `components[].value`    | number or null                                            |                                                                                                                                                                          |
| `components[].unit`     | `money`, `count`, `percent`, `days`, `minutes`, `hours`   |                                                                                                                                                                          |
| `components[].count`    | integer                                                   |                                                                                                                                                                          |
| `components[].notes`    | array of string                                           |                                                                                                                                                                          |
| `completeness`          | object                                                    |                                                                                                                                                                          |
| `completeness.complete` | boolean                                                   |                                                                                                                                                                          |
| `completeness.reasons`  | array of string                                           |                                                                                                                                                                          |
| `rows`                  | array of objects                                          | Grouped rows, when `groupBy` was asked; empty otherwise.                                                                                                                 |
| `rows[].key`            | string                                                    | The row's id: a crew, service, customer, or other grouping key.                                                                                                          |
| `rows[].label`          | string                                                    | The row's name.                                                                                                                                                          |
| `rows[].value`          | number or null                                            | The row's number.                                                                                                                                                        |
| `rows[].count`          | integer                                                   | How many records sit behind it.                                                                                                                                          |
| `rows[].notes`          | array of string                                           | Native cohort or provenance cautions for this row.                                                                                                                       |
| `truncated`             | boolean                                                   | Whether more than 50 rows existed.                                                                                                                                       |
| `coverage`              | object                                                    | How much of the data the number covers. Say so when `included` is less than `total`.                                                                                     |
| `coverage.included`     | integer                                                   | Records counted.                                                                                                                                                         |
| `coverage.total`        | integer                                                   | Records that could have been.                                                                                                                                            |
| `coverage.unit`         | string                                                    | What a record is, e.g. `invoices`.                                                                                                                                       |
| `asOf`                  | timestamp                                                 | When it was worked out.                                                                                                                                                  |
| `reportUrl`             | string                                                    | The Reports page that shows the same number.                                                                                                                             |

## Example

```json
{
  "object": "metric",
  "metric": "Example metric",
  "name": "Weekly mowing",
  "unit": "money",
  "definition": "Example definition",
  "status": "ok",
  "value": 45,
  "period": {
    "from": "Example from",
    "to": "Example to",
    "label": "Home"
  },
  "previous": {
    "value": 45,
    "label": "Home"
  },
  "usual": {
    "status": "ok",
    "lower": 45,
    "upper": 45,
    "sampleCount": 1,
    "required": 12,
    "method": "linear_p10_p90",
    "windows": [
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      },
      {
        "from": "Example from",
        "to": "Example to",
        "value": 45
      }
    ]
  },
  "components": [
    {
      "key": "Example key",
      "label": "Home",
      "status": "available",
      "value": 45,
      "unit": "money",
      "count": 1,
      "notes": [
        "Example note"
      ]
    }
  ],
  "completeness": {
    "complete": true,
    "reasons": [
      "Customer asked to pause for the winter."
    ]
  },
  "rows": [
    {
      "key": "Example key",
      "label": "Home",
      "value": 45,
      "count": 1,
      "notes": [
        "Example note"
      ]
    }
  ],
  "truncated": true,
  "coverage": {
    "included": 1,
    "total": 1,
    "unit": "Example unit"
  },
  "asOf": "2026-10-16T17:04:12.381Z",
  "reportUrl": "https://example.com/shortcut/webhooks"
}
```

## Endpoints

| Endpoint                 | What it does          |
| ------------------------ | --------------------- |
| `GET /v1/reports/metric` | Get a business number |
