# dashboardMetrics

query · in the family [Reading your records](/reference/reading-your-records/)

## What it does

One dashboard’s widgets answered with live figures — counts and per-currency totals computed at read time, each stamped with when it was read.

One dashboard's widgets ANSWERED: each canned metric computed at read time, ordinal-ordered. The lanes: bounded status counts (orders_open = open/held/placed · cs_open_cases = cases where work remains · fraud_alerts_open = awaiting first triage) · windowed sales sums PER CURRENCY (sales_today = the UTC calendar day · sales_week = the trailing 7 days; placed/completed orders by creation instant, never cross-currency) · loyalty_signups_30d (members created in the trailing 30 days — a signup is a birth event, status-blind) · inventory_value (Σ on-hand × weighted-average cost per currency; items without a cost basis are excluded) · sell_through_30d · review_average (the published-review aggregate — the average ×100 beside its census) · low_stock_count (the per-organization buy-desk snapshots summed — every ACTIVE organization must have been desk-evaluated, asOf = the oldest evaluation; an unevaluated organization refuses naming it). EVERY answer is honest-or-absent: a lane whose rows exceed the per-lane walk cap (2000), nothing to measure yet, or a sum past the wire's integer ceiling answers available:false with a plain-words reason — never a clipped figure. Group-wide (the construct's own scope). The dashboard must exist in YOUR org group. Requires authentication (template class).

## What happens

Read-only. Every tile answers honestly or not at all: a figure that cannot be totaled truthfully (too many records for one glance, or a summary that has not been built yet) says so in plain words instead of guessing.

## Who may call it

Capability area: **Reading your records** — Looking up and listing the records of your organization.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- An API key whose scope allows `api:dashboardMetrics`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | yes | The id of the record. |

## Returns

[DashboardMetrics](/types/DashboardMetrics/) `DashboardMetrics!` — The dashboardMetrics answer — the layout's widgets, each realized at read time.

## Example request

```graphql
query ExampleDashboardMetrics($id: ID!) {
  dashboardMetrics(id: $id) {
    dashboardId
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000"
}
```

## Example response

```json
{
  "data": {
    "dashboardMetrics": {
      "dashboardId": "01900000-0000-7000-8000-71d51a360000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))

## Used in

- [Build a dashboard](/use-cases/build-a-dashboard/)