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

> Headline usage and value for the caller, or for their whole organisation: sessions, active users, hours saved and cost saved.

> [!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 the headline figures from Wordsmith's **Usage and value** dashboard for a period: how much work Wordsmith did and what it saved. Use it to show a user their own impact, or to report ROI for the organisation.

`scope` decides whose figures you get:

* `me`: the caller's own usage. Anyone can read it, unless the organisation turned personal figures off. When it hides cost figures, both cost figures read `0`.
* `company`: the whole organisation. Only people allowed to view company analytics, usually admins, can read it. Others get `403 forbidden`.

Hours and cost saved are estimates. Wordsmith estimates how long each piece of work would have taken a lawyer, and prices it with your organisation's in-house and external counsel rates. Admins set the rates and seniority levels in Wordsmith. Organisation figures (`scope=company`) apply the organisation's calibration setting (conservative, balanced or ambitious), so they match the dashboard; personal figures are never calibrated, as on the dashboard. Credit and token consumption is not part of this API.

## Authentication

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

## Query parameters

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

`me` or `company`.

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

`this_month`, `last_month`, `last_7_days`, `last_30_days`, `last_quarter`, `lifetime` or `custom`. `last_quarter` is the last complete quarter of your organisation's financial year.

**start** `string`

ISO date, such as `2026-09-01`. Required when `period` is `custom`.

**end** `string`

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

**user\_ids** `string`

Company scope only: comma-separated user ids to limit the figures to.

**team\_ids** `string`

Company scope only: comma-separated team ids. Teams expand to their members.

**agent\_ids** `string`

Company scope only: comma-separated agent ids.

## Response

Returns `200`. Each figure carries the value for the period (`current`) and for the period before it (`previous`), so you can show the trend. `previous` is `null` when there is no earlier period to compare, as for `lifetime`. `active_users` is `null` for `scope=me`.

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

```json Company theme={null}
{
  "scope": "company",
  "period": { "label": "Q3 2026", "start": "2026-07-01", "end": "2026-09-30" },
  "currency": "GBP",
  "sessions": { "current": 4182, "previous": 3610 },
  "interactions": { "current": 15930, "previous": 13204 },
  "active_users": { "current": 214, "previous": 198 },
  "hours_saved": { "current": 6240.5, "previous": 5310.0 },
  "cost_saved_external": { "current": 2496200, "previous": 2124000 },
  "cost_saved_in_house": { "current": 748860, "previous": 637200 },
  "report_cells_computed": { "current": 48210, "previous": 31975 }
}
```

```json Me theme={null}
{
  "scope": "me",
  "period": { "label": "October 2026", "start": "2026-10-01", "end": "2026-10-31" },
  "currency": "GBP",
  "sessions": { "current": 37, "previous": 52 },
  "interactions": { "current": 141, "previous": 188 },
  "active_users": null,
  "hours_saved": { "current": 41.5, "previous": 63.0 },
  "cost_saved_external": { "current": 16600, "previous": 25200 },
  "cost_saved_in_house": { "current": 4980, "previous": 7560 },
  "report_cells_computed": { "current": 320, "previous": 140 }
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `period` or `scope` is unknown, `custom` is missing `start` or `end`, a date is not ISO, a company filter was sent with `scope=me`, or a `user_ids`, `team_ids` or `agent_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` | `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.