# Account usage as a time series

`GET /v1/console/usage/series` (operation id `getUsageSeries`)

Authentication: Console session cookie (`__Host-dex_session`). State-changing routes also need the `x-dex-csrf` header.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `start` | query | string | yes | First UTC date included. (format date) |
| `end` | query | string | yes | First UTC date not included. (format date) |
| `granularity` | query | string | no | (one of "day", "hour"; default "day") |
| `group_by` | query | string | no | (one of "none", "key", "model", "served_by"; default "none") |

## Responses

### 200

One series per group.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | (always "usage_series") |
| `start` | string | yes | (format date) |
| `end` | string | yes | (format date) |
| `granularity` | string | yes | (one of "day", "hour") |
| `group_by` | string | yes | (one of "none", "key", "model", "served_by") |
| `series` | array of object | yes |  |
| `series[].group` | string \| null | yes | The key id, model or served_by value; null when group_by is none. |
| `series[].points` | array of UsageBucket | yes |  |
| `series[].points[].start` | string | yes | (format date-time) |
| `series[].points[].end` | string | yes | (format date-time) |
| `series[].points[].requests` | integer | yes | Successful (billed or test) decide calls. |
| `series[].points[].input_tokens` | integer | yes | (format int64) |
| `series[].points[].charge_micro_cents` | integer | yes | (format int64) |
| `series[].points[].gpu_requests` | integer | yes |  |
| `series[].points[].fallback_requests` | integer | yes |  |
| `series[].points[].error_requests` | integer | yes | Calls that ended in an error. Never charged. |

### 401

Missing, unknown, revoked or expired credentials.

### 403

The credentials are valid but not allowed to do this (missing scope, suspended account or failed CSRF check).

### 422

The request is well-formed JSON but breaks a validation rule. `param` names the field as a dotted path.
Codes: `unknown_field`, `missing_field`, `invalid_type` (wrong JSON type), `invalid_value` (right type, value
out of range: an empty or over-long string, a state, `instructions`, `criteria` string or option description
of only whitespace, an empty `questions` or `options` object, an empty state object or array, a pattern or
allowed-value mismatch such as a label or level with outer whitespace, a state nested deeper than 32 levels, a
bad date or date range), `field_not_allowed` (`options` or `levels` on the wrong question type),
`invalid_question_id`, `too_many_questions`, `too_many_options`, `invalid_levels` (including two levels equal
after Unicode NFC normalisation and lower-casing), `invalid_min_confidence`, `duplicate_label` (two option
labels equal after Unicode NFC normalisation and lower-casing, such as `Billing` and `billing`),
`state_path_not_found`, `state_not_json` and, on the console, `top_up_limit_exceeded`.


### 500

An unexpected error. Any charge was refunded. Retry with the same idempotency key.

### 503

`maintenance`: the console's database, sign-in or payments are unavailable for a moment. Retry after
`retry-after`. Nothing was changed.


## Examples

Illustrative values. Examples show the shape of requests and responses; the numbers in them are not measured results.

Response: Hourly usage split by serving path

```json
{
  "object": "usage_series",
  "start": "2026-10-20",
  "end": "2026-10-21",
  "granularity": "hour",
  "group_by": "served_by",
  "series": [
    {
      "group": "gpu",
      "points": [
        {
          "start": "2026-10-20T09:00:00Z",
          "end": "2026-10-20T10:00:00Z",
          "requests": 1204,
          "input_tokens": 411380,
          "charge_micro_cents": 2056900,
          "gpu_requests": 1204,
          "fallback_requests": 0,
          "error_requests": 1
        }
      ]
    },
    {
      "group": "fallback",
      "points": [
        {
          "start": "2026-10-20T09:00:00Z",
          "end": "2026-10-20T10:00:00Z",
          "requests": 3,
          "input_tokens": 1022,
          "charge_micro_cents": 5110,
          "gpu_requests": 0,
          "fallback_requests": 3,
          "error_requests": 0
        }
      ]
    }
  ]
}
```