Usage

The Usage resource provides programmatic access to the same data available in the Thinklio dashboard — token consumption, cost attribution, budget status, and interaction counts.

Aggregation

Usage data is available at multiple aggregation levels: org, team, agent, and individual user. All queries support date range filtering.

Cost Attribution

Costs are attributed to the entity that initiated the work:

Channel API interactions — attributed to the user on whose behalf the message was sent
Platform API jobs — attributed to the org or team associated with the API key
Integration API tool executions — attributed to the agent's interaction context

Budget Status

The usage endpoint returns current budget consumption alongside limits. Use this to build dashboards, trigger alerts, or implement custom budget enforcement in your own systems.

Export

Usage data can be exported as CSV or JSONL for integration with external billing or analytics systems. Exports are generated asynchronously and delivered to a configured S3-compatible destination.

Endpoints

GET/v1/usageComing Soon

Query usage data

Retrieve token consumption, cost attribution, and budget status for your organisation. Supports filtering by time range, team, agent, or API surface.

Parameters

Name	Type	In	Required	Description
from	string	query	No	Start of the date range (ISO 8601). Defaults to the start of the current calendar month.
to	string	query	No	End of the date range (ISO 8601). Defaults to now.
group_by	string	query	No	Aggregation dimension: org, team, agent, user, or surface.
team_id	string	query	No	Filter to a specific team.

Response

{
  "period": {
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-19T12:00:00Z"
  },
  "total_tokens": 1240000,
  "budget": {
    "total": 5000000,
    "used": 1240000,
    "remaining": 3760000
  },
  "breakdown": [
    {
      "dimension": "team_id",
      "value": "tm_01hxyz",
      "label": "Support Team",
      "tokens": 840000
    }
  ]
}