usage

Management

Usage

View Scenario usage analytics for selected projects, users, and dates. Default response: after-discount CU totals, per-user consumption, per-model CU/jobs sorted by CU, and asset-kind counts. Use this for top models, top consumers, or models per user. Expand time buckets and activity only when needed. Args: - scope: 'project' (default) or 'team' for all projects the credential can access. OAuth still needs a context project for team queries. Permission restrictions continue to apply. - response_format: 'json' (default) or 'markdown'. Accounting: totals.totalCU sums consumption.value, the CU cost already after discounts. Raw consumption.total equals value + discount (before-discount CU). Model totalCU sums point.cost, also already after discounts; never subtract discounts again. totalApiKeyCU is a subset. Model series count generation activity and exclude separately recorded refunds and non-model operations, so model totals need not equal overall consumption. Do not infer the cause of a difference from its amount; inspect usages.daily/activity. Job billing snapshots are not a consumption ledger. Returns: { scope, totals, consumption, modelUsages, assetUsages, sections, _hint }, plus requested sections and activityPagination when activity is included. Scope echoes filters sent to the API, not additional access rights. Examples: - "Top models in this project" -> project_id=<selected project>, plus dates; rank modelUsages by totalCU or totalJobs. - "Top models across all projects" -> scope='team', team_id/project_id as authentication context, plus dates. - "Top five models for one user" -> same scope and dates, user_ids=[<user ID>]. - "Explain a CU difference" -> include=['usages.daily','activity'], then follow activityPagination.nextOffset. Don't use when: You need per-job execution state or cancellation. Prefer job_get / jobs_wait / jobs_list / job_cancel instead. Your own consumption cap and remaining CU: consumption_limit_get (catalog-only, run via scenario_tool_execute_read).

read-onlyidempotentopen-world

Parameters

Name	Type	Required	Description
team_id	string	—	Team ID. Required with project_id for OAuth callers; an API key is scoped by the key.
project_id	string	—	Authentication context and default analytics project. For all accessible projects, set scope=team.
scope	enum(project \| team)	project	project filters to project_ids or project_id. team requests all projects accessible to this credential; it does not grant additional access.
project_ids	array	—	Analytics project filters within the selected team. Overrides project_id for filtering only. Cannot be combined with scope=team.
user_ids	array	—	Filter analytics to these user/API identity IDs. Use one ID per call for models per user. Access restrictions still apply.
start_date	unknown	—	Inclusive ISO start date. Supply both dates; the API enforces its maximum time range. Defaults to the last 31 days if both are omitted.
end_date	unknown	—	Inclusive ISO end date. For a complete calendar period use its final millisecond, e.g. 2026-03-31T23:59:59.999Z.
include	array	—	Expand sections: usages (usage-type totals), usages.daily (time buckets), modelUsages.daily (model time buckets), nsfwUsages, activity (up to 100 events), entities (ID lookups).
activity_offset	number	—	Activity offset, default 0. Requires include=['activity']. Follow activityPagination.nextOffset until null.
response_format	enum(json \| markdown)	json	Output format: 'json' for structured data, 'markdown' for human-readable text.

Example Request

JSON

{
  "team_id": "team_abc123",
  "project_id": "proj_xyz789",
  "start_date": "2026-03-01T00:00:00Z",
  "end_date": "2026-03-31T23:59:59.999Z"
}

Example Response

JSON

{
  "scope": {
    "mode": "project",
    "teamId": "team_abc123",
    "contextProjectId": "proj_xyz789",
    "projectIds": [
      "proj_xyz789"
    ],
    "userIds": null
  },
  "totals": {
    "totalCU": 80,
    "totalDiscountCU": 20,
    "totalBeforeDiscountCU": 100,
    "users": 1,
    "startDate": "2026-03-01T00:00:00Z",
    "endDate": "2026-03-31T23:59:59.999Z"
  },
  "consumption": [
    {
      "userId": "user_example",
      "value": 80,
      "discount": 20,
      "total": 100
    }
  ],
  "modelUsages": [
    {
      "modelId": "model_example",
      "modelName": "Example Model",
      "totalCU": 80,
      "totalDiscountCU": 20,
      "totalJobs": 4,
      "totalApiKeyCU": 0,
      "totalApiKeyDiscountCU": 0
    }
  ],
  "assetUsages": [
    {
      "kind": "image",
      "total": 4,
      "totalApiKey": 0
    }
  ]
}

Common Use Cases

Rank model CU and job counts for a project or scope=team across accessible projects
Filter user_ids to answer top models per user from usage analytics
Inspect paginated activity to investigate differences without guessing refunds