Get Usage Over Time

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

GET /api/v1/usage/timeseries

cURL

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"

Response

{
  "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 }
  ]
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

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: 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.

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.

cURL

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"

Response

{
  "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.