Usage

Query metered LLM consumption (requests, tokens, cost).

Get usage report

get

Returns metered LLM consumption (requests, tokens, cost) for the caller's scope as a daily UTC series or range totals, optionally grouped by team or API key. A bare call returns the last 30 days for the calling key's scope. Range caps: 90 days, or 31 days when group_by is combined with granularity=day. All dates are UTC calendar days; cost is USD. Rows for the current UTC day are partial.

Access levels gate how you may slice. A company owner's key reaches every team and API key in the company and may use both group_by dimensions. A team API key (or a team owner's key) reaches only its own team: team_id must name that team, api_key_id only keys belonging to it, and group_by is limited to api_key. A member's key reaches only that member's own keys. Any team_id, api_key_id, or group_by beyond the caller's reach fails the whole request with 403 — results are never silently truncated. Filters that match nothing within the caller's scope return zero-filled rows.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

fromstring · dateOptional

Inclusive range start (UTC), YYYY-MM-DD. Defaults to to minus 30 days.

tostring · dateOptional

Inclusive range end (UTC), YYYY-MM-DD. Defaults to today (UTC); must not be in the future.

granularitystring · enumOptional

day — one zero-filled row per UTC day; total — range totals only.

Default: dayPossible values:

group_bystring · enumOptional

Adds a groups array sliced by the given dimension.

Possible values:

team_idstring · uuid[]Optional

Restrict to these teams (repeatable, max 100).

api_key_idstring · uuid[]Optional

Restrict to these API keys (repeatable, max 100). Combines with team_id as AND — a key outside the filtered teams yields zero-filled rows, not an error.

order_bystring · enumOptional

Ranks groups descending; only meaningful with group_by.

Default: cost_totalPossible values:

limitinteger · int32 · min: 1 · max: 100Optional

Max groups returned (1-100), ranked by order_by.

Default: 25

include_otherbooleanOptional

When limit truncates, append one synthetic __other__ group aggregating the rest so group totals reconcile with response totals.

Default: true

top_models_limitinteger · int32 · min: 1 · max: 20Optional

Max model rows (1-20); the __other__ rollup row does not count.

Default: 5

top_models_rank_bystring · enumOptional

Ranking dimension for top models.

Default: cost_totalPossible values:

Responses

200

Usage report for the requested scope.

application/json

fromstring · dateRequiredExample: 2026-08-09

tostring · dateRequiredExample: 2026-08-10

granularitystring · enumRequiredPossible values:

group_bystring · enumOptionalPossible values:

400

Error response

application/json

401

Error response

application/json

403

Error response

application/json

get/v1/usage

GET /v1/usage HTTP/1.1
Host: api.nexos.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "from": "2026-08-09",
  "to": "2026-08-10",
  "granularity": "day",
  "group_by": "team",
  "totals": {
    "requests": 1204,
    "tokens_input": 423599,
    "tokens_output": 67889,
    "tokens_cache_write": 3918,
    "tokens_cache_write_1h": 0,
    "tokens_cache_read": 74020,
    "tokens_total": 569426,
    "cost_total": 18.66
  },
  "items": [
    {
      "date": "2026-08-09",
      "top_models": [
        {
          "model": "gpt-4o",
          "requests": 1204,
          "tokens_input": 423599,
          "tokens_output": 67889,
          "tokens_cache_write": 3918,
          "tokens_cache_write_1h": 0,
          "tokens_cache_read": 74020,
          "tokens_total": 569426,
          "cost_total": 18.66
        }
      ],
      "requests": 1204,
      "tokens_input": 423599,
      "tokens_output": 67889,
      "tokens_cache_write": 3918,
      "tokens_cache_write_1h": 0,
      "tokens_cache_read": 74020,
      "tokens_total": 569426,
      "cost_total": 18.66
    }
  ],
  "groups": [
    {
      "dimensions": {
        "team_id": "text",
        "team_name": "text",
        "api_key_id": "text",
        "api_key_name": "text"
      },
      "totals": {
        "requests": 1204,
        "tokens_input": 423599,
        "tokens_output": 67889,
        "tokens_cache_write": 3918,
        "tokens_cache_write_1h": 0,
        "tokens_cache_read": 74020,
        "tokens_total": 569426,
        "cost_total": 18.66
      },
      "items": [
        {
          "date": "2026-08-09",
          "top_models": [
            {
              "model": "gpt-4o",
              "requests": 1204,
              "tokens_input": 423599,
              "tokens_output": 67889,
              "tokens_cache_write": 3918,
              "tokens_cache_write_1h": 0,
              "tokens_cache_read": 74020,
              "tokens_total": 569426,
              "cost_total": 18.66
            }
          ],
          "requests": 1204,
          "tokens_input": 423599,
          "tokens_output": 67889,
          "tokens_cache_write": 3918,
          "tokens_cache_write_1h": 0,
          "tokens_cache_read": 74020,
          "tokens_total": 569426,
          "cost_total": 18.66
        }
      ]
    }
  ],
  "top_models": [
    {
      "model": "gpt-4o",
      "requests": 1204,
      "tokens_input": 423599,
      "tokens_output": 67889,
      "tokens_cache_write": 3918,
      "tokens_cache_write_1h": 0,
      "tokens_cache_read": 74020,
      "tokens_total": 569426,
      "cost_total": 18.66
    }
  ]
}