> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage Over Time

> One usage or value metric over time, for the caller or the organisation.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Returns one metric as a series of points, ready to chart: sessions per week, hours saved per month, and so on. `scope` works as in [Get Usage Summary](/api-reference/usage/get-usage-summary): `me` for the caller, `company` for the organisation.

`cost_saved` is the external counsel cost saved.

## Authentication

Requires an API key, or an OAuth token with `usage:read`.

## Query parameters

**metric** `string` *required*

`sessions`, `interactions`, `active_users` (company only), `hours_saved` or `cost_saved`. With `scope=company`, hours and cost apply the organisation's calibration setting, as on the dashboard.

**scope** `string` (default: me)

`me` or `company`.

**grain** `string` (default: auto)

`day`, `week`, `month`, or `auto`: days up to 31 days, weeks up to 120 days, months beyond.

**period** `string` (default: last\_30\_days)

As in [Get Usage Summary](/api-reference/usage/get-usage-summary).

**start** `string`

ISO date. Required when `period` is `custom`.

**end** `string`

ISO date. Required when `period` is `custom`.

**agent\_id** `string`

Company scope only: the series for one agent.

**team\_id** `string`

Company scope only: the series for one team.

## Response

Returns `200` with the resolved `period`, the `grain` used and `points`, oldest first. Each point covers `start` to `end`.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/usage/timeseries?metric=hours_saved&scope=company&grain=month&period=last_quarter" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "metric": "hours_saved",
  "scope": "company",
  "grain": "month",
  "period": { "label": "Q3 2026", "start": "2026-07-01", "end": "2026-09-30" },
  "points": [
    { "label": "2026-07", "start": "2026-07-01", "end": "2026-07-31", "value": 1890.5 },
    { "label": "2026-08", "start": "2026-08-01", "end": "2026-08-31", "value": 2044.0 },
    { "label": "2026-09", "start": "2026-09-01", "end": "2026-09-30", "value": 2306.0 }
  ]
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `metric`, `scope`, `grain` or `period` is unknown, `custom` is missing a date, `active_users` was asked for with `scope=me`, a company filter was sent with `scope=me`, or `agent_id` or `team_id` is not one in your organisation (the message names it). |
| 403 | `insufficient_scope` | The OAuth token does not hold `usage:read`. |
| 403 | `forbidden` | `scope=company` and the caller cannot view company analytics; or `scope=me` and the organisation turned personal figures off. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.