AI (v1)

Get AI usage

Retrieve aggregated AI usage for the tenant, including token counts, credits consumed, and cost in US dollars. Results can be filtered by time range, team, model, provider, feature, story, user, or action, and optionally grouped by one of these dimensions.

Admins see usage across the entire tenant. Non-admin users see usage from teams they belong to, plus usage rows not attributed to any team.

Supply either relative_date or the start_date/end_date pair, not both.

get/api/v1/ai_usage

Request

  • Base URL: https://your-tenant.tines.com
  • URL: https://your-tenant.tines.com/api/v1/ai_usage
  • Auth: one of:
    • API key in header X-User-Token
    • HTTP bearer

Query parameters

relative_datestring

Predefined time window relative to now, for example today, yesterday, 7 days, 30 days, 3 months, or 1 year. Defaults to 30 days. Cannot be combined with start_date and end_date

start_datestring

ISO 8601 timestamp for the start of a custom time window. Must be paired with end_date

end_datestring

ISO 8601 timestamp for the end of a custom time window. Must be paired with start_date, must be after start_date, and the window cannot exceed one year

team_idinteger

Only return usage attributed to the specified team. Non-admin users requesting usage for a team they don't belong to receive a zeroed response

model_idstring

Only return usage attributed to the specified model

provider_idinteger

Only return usage attributed to the specified provider

feature'workbench' | 'workbench_storyboard' | 'ai_agents' | 'workbench_cases' | 'workbench_apps' | 'other'

Only return usage attributed to the specified feature

story_idinteger

Only return runtime usage from AI actions and AI agents in the specified story. Non-admin users only see usage from teams they belong to, so requesting a story outside those teams returns a zeroed response

user_idinteger

Only return usage initiated by the specified user. Non-admin users can only attribute usage to users they can see, so requesting any other user returns a zeroed response

action_idinteger

Only return runtime usage from the specified AI action or AI agent. An AI action used as a tool by an agent reports its own usage under its own ID, not the agent's. Non-admin users only see usage from teams they belong to, so requesting an action outside those teams returns a zeroed response

group_by'model' | 'provider' | 'team' | 'feature' | 'story' | 'user' | 'action' | 'day'

Break the response into per-bucket groups along one dimension. When omitted, only the totals are returned

Response

Successful response

group_bystring nullable

Echoes the group_by parameter when provided. Omitted when group_by is not set

Changes

No recorded changes to this operation across all 1 revision of this API.