Get Usage Breakdown

curl "https://api.wordsmith.ai/api/v1/usage/breakdown?dimension=agent&period=last_quarter" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

{
  "dimension": "agent",
  "period": { "label": "Q3 2026", "start": "2026-07-01", "end": "2026-09-30" },
  "currency": "GBP",
  "items": [
    {
      "key": "5d0e8b47-1c3a-4f96-8e2b-7a4c9d1f0e63",
      "label": "Commercial contracts",
      "sessions": 1904,
      "interactions": 7212,
      "invocations": null,
      "active_users": 122,
      "hours_saved": 2810.0,
      "cost_saved_external": 1124000,
      "cost_saved_in_house": 337200
    },
    {
      "key": "b81f3c06-9d2e-4a57-b4c1-0e6a8f2d7c95",
      "label": "Employment",
      "sessions": 733,
      "interactions": 2655,
      "invocations": null,
      "active_users": 58,
      "hours_saved": 964.5,
      "cost_saved_external": 385800,
      "cost_saved_in_house": 115740
    }
  ],
  "cursor": null
}

GET

api

usage

breakdown

curl "https://api.wordsmith.ai/api/v1/usage/breakdown?dimension=agent&period=last_quarter" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

{
  "dimension": "agent",
  "period": { "label": "Q3 2026", "start": "2026-07-01", "end": "2026-09-30" },
  "currency": "GBP",
  "items": [
    {
      "key": "5d0e8b47-1c3a-4f96-8e2b-7a4c9d1f0e63",
      "label": "Commercial contracts",
      "sessions": 1904,
      "interactions": 7212,
      "invocations": null,
      "active_users": 122,
      "hours_saved": 2810.0,
      "cost_saved_external": 1124000,
      "cost_saved_in_house": 337200
    },
    {
      "key": "b81f3c06-9d2e-4a57-b4c1-0e6a8f2d7c95",
      "label": "Employment",
      "sessions": 733,
      "interactions": 2655,
      "invocations": null,
      "active_users": 58,
      "hours_saved": 964.5,
      "cost_saved_external": 385800,
      "cost_saved_in_house": 115740
    }
  ],
  "cursor": null
}

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

Splits the organisation’s usage and value along one dimension, such as which agents save the most time or which teams use Wordsmith most. It is the table under the charts in the Usage and value dashboard. This endpoint covers the whole organisation, so only people allowed to view company analytics can call it. Per-person rows (dimension=user) also need the named-users entitlement; without it they return 403 forbidden. Each dimension records different figures, as on the dashboard. A row carries the figures its dimension records and null for the rest:

`dimension`	Figures
`agent`	`sessions`, `interactions`, `active_users`, `hours_saved`, `cost_saved_external`, `cost_saved_in_house`
`team`, `user`	`sessions`, `interactions`, `hours_saved`, `cost_saved_external`, `cost_saved_in_house`; teams also `active_users`
`skill`	`invocations`, `active_users`
`surface`	`sessions`, `interactions`
`work_type`	`sessions`
`seniority`, `role`, `region`	`interactions`, `cost_saved_external`, `cost_saved_in_house`

key is the agent, skill, team or user id, or the stored value for the other dimensions. label is what the dashboard shows.

Authentication

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

Query parameters

string

required

agent, skill, surface (web, Slack, Word add-in, …), work_type, team, seniority, role, region or user.

string

default:"this_month"

As in Get Usage Summary.

string

ISO date. Required when period is custom.

string

ISO date. Required when period is custom.

string

Comma-separated user ids to limit the rows to.

string

Comma-separated team ids to limit the rows to.

string

The cursor from the previous page.

integer

default:"20"

Rows per page, up to 50.

Response

Hours and cost saved apply the organisation’s calibration setting, as on the dashboard. Returns 200 with rows sorted by hours_saved, largest first. Dimensions without hours sort by their first count.

curl "https://api.wordsmith.ai/api/v1/usage/breakdown?dimension=agent&period=last_quarter" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

{
  "dimension": "agent",
  "period": { "label": "Q3 2026", "start": "2026-07-01", "end": "2026-09-30" },
  "currency": "GBP",
  "items": [
    {
      "key": "5d0e8b47-1c3a-4f96-8e2b-7a4c9d1f0e63",
      "label": "Commercial contracts",
      "sessions": 1904,
      "interactions": 7212,
      "invocations": null,
      "active_users": 122,
      "hours_saved": 2810.0,
      "cost_saved_external": 1124000,
      "cost_saved_in_house": 337200
    },
    {
      "key": "b81f3c06-9d2e-4a57-b4c1-0e6a8f2d7c95",
      "label": "Employment",
      "sessions": 733,
      "interactions": 2655,
      "invocations": null,
      "active_users": 58,
      "hours_saved": 964.5,
      "cost_saved_external": 385800,
      "cost_saved_in_house": 115740
    }
  ],
  "cursor": null
}

Errors

Status	`error_code`	When
400	`bad_request`	`dimension` or `period` is unknown, `limit` is outside 1 to 50, `cursor` is not valid, `dimension=team` while teams are not enabled, or a `user_ids` or `team_ids` entry is not one in your organisation (the message names it).
403	`insufficient_scope`	The OAuth token does not hold `usage:read`.
403	`forbidden`	The caller cannot view company analytics, or asked for `user` rows without the named-users entitlement.

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Query parameters

Response

Errors

​Authentication

​Query parameters

​Response

​Errors

Authentication

Query parameters

Response

Errors