Usage

`GET /v1/usage` — pull your account's token usage and spend by model, region, and time bucket. Tomoul-native (not in OpenAI spec).

Endpoint

GET https://api.tomoul.ai/v1/usage

Query params

Param	Notes
`start`	ISO 8601 timestamp. Required.
`end`	ISO 8601 timestamp. Default: now.
`bucket`	`hour`, `day`, or `month`. Default: `day`.
`group_by`	Comma-separated. Any of: `model`, `region`, `key`.

curl "https://api.tomoul.ai/v1/usage?start=2026-05-01&group_by=model,region" \
  -H "Authorization: Bearer $TOMOUL_KEY"

Response

{
  "buckets": [
    {
      "start":   "2026-05-10T00:00:00Z",
      "end":     "2026-05-11T00:00:00Z",
      "model":   "microsoft/phi-4",
      "region":  "eu-helsinki1",
      "prompt_tokens":      1842301,
      "completion_tokens":  482910,
      "cache_read_tokens":  93120,
      "cost_usd":           4.83
    }
  ],
  "totals": {
    "prompt_tokens":     1842301,
    "completion_tokens": 482910,
    "cache_read_tokens": 93120,
    "cost_usd":          4.83
  }
}

Use this endpoint to reconcile against your monthly invoice, or to surface spend in your own internal dashboards. It returns the same data the console uses — there is no separate "rolled-up" copy.

← Previous

Audio

Last updated 13 May 2026Edit this page on GitHub