Skip to main content
GET
Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.
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

​
string
default:"me"
me or company.
​
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.
​
string
ISO date, such as 2026-09-01. Required when period is custom.
​
string
ISO date. Required when period is custom.
​
string
Company scope only: comma-separated user ids to limit the figures to.
​
string
Company scope only: comma-separated team ids. Teams expand to their members.
​
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.

​
Errors