> ## 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 Breakdown

> Break your organisation's usage and value down by agent, skill, surface, kind of work, team, seniority, role, region or person.

> [!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).

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

**dimension** `string` *required*

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

**period** `string` (default: this\_month)

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

**user\_ids** `string`

Comma-separated user ids to limit the rows to.

**team\_ids** `string`

Comma-separated team ids to limit the rows to.

**cursor** `string`

The `cursor` from the previous page.

**limit** `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.

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

```json Response theme={null}
{
  "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. |


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