aimldocs

Usage

per-request lookups and the activity feed

GET
/v1/generation/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string
Match^[0-9A-HJKMNP-TV-Z]{26}$

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/generation/string"
{  "id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE",  "created": "2026-09-10T11:59:00.123Z",  "model": "openai/gpt-5-mini",  "resolved": {    "provider": "openai",    "endpoint_id": "ep_openai_gpt-5-mini_us",    "upstream_model": "gpt-5-mini",    "region": "us"  },  "usage": {    "input_tokens": 812,    "output_tokens": 143,    "cache_read_tokens": 0,    "cache_write_tokens": 0,    "reasoning_tokens": 0  },  "cost": {    "total_micro_usd": 489,    "lines": [      {        "kind": "input",        "units": 812,        "unit_price_nano": 250,        "micro_usd": 203      },      {        "kind": "output",        "units": 143,        "unit_price_nano": 2000,        "micro_usd": 286      }    ],    "price_version": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01"  },  "timing": {    "ttft_ms": 190,    "duration_ms": 1420,    "gw_overhead_ms": 4  },  "stop": {    "reason": "end_turn"  },  "attempts": [    {      "attempt": 1,      "provider": "openai",      "outcome": "ok",      "http_status": 200,      "ttft_ms": 186    }  ],  "warnings": []}
GET
/v1/requests
AuthorizationBearer <token>

In: header

Query Parameters

since?string
Formatdate-time
until?string
Formatdate-time
project_id?string
key_id?string
model?string
provider?string
status?string
errors_only?boolean
fallbacks_only?boolean
min_cost_micro?integer
max_cost_micro?integer
q?string

request id prefix

limit?integer
Rangevalue <= 500
Default50
format?unknown

csv returns every matching request as one text/csv file (not a page), at most 200,000 rows; a larger result is refused with export_too_large

Value in

  • "json"
  • "csv"
cursor?string

Response Body

application/json

curl -X GET "https://example.com/v1/requests"
{  "object": "list",  "data": [    {      "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE",      "ts": "2026-09-10 11:59:00.123",      "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0F1PRJ1",      "key_id": "key_01J9ZK2K4Q7Q3M3QX1V0F1KEY1",      "model": "openai/gpt-5-mini",      "provider": "openai",      "endpoint_id": "ep_openai_gpt-5-mini_us",      "region": "us",      "status": "ok",      "http_status": 200,      "error_code": "",      "stop_reason": "end_turn",      "attempts": 1,      "input_tokens": 812,      "cache_read_tokens": 0,      "output_tokens": 143,      "usage_source": "provider",      "cost_micro": 489,      "ttft_ms": 190,      "duration_ms": 1420,      "stream": true,      "byok": false,      "zdr": false,      "logged": true,      "app_id": "chatbot",      "user_hash": ""    }  ],  "next_cursor": "c2"}
GET
/v1/requests/tail
AuthorizationBearer <token>

In: header

Query Parameters

after?string

resume after this request id

interval_ms?integer
Range500 <= value <= 30000
Default2000

Response Body

text/event-stream

application/json

curl -X GET "https://example.com/v1/requests/tail"
"string"
GET
/v1/requests/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/requests/string"
{  "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE",  "ts": "2026-09-10 11:59:00.123",  "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0F1PRJ1",  "key_id": "key_01J9ZK2K4Q7Q3M3QX1V0F1KEY1",  "model": "openai/gpt-5-mini",  "provider": "openai",  "endpoint_id": "ep_openai_gpt-5-mini_us",  "region": "us",  "status": "ok",  "http_status": 200,  "error_code": "",  "stop_reason": "end_turn",  "attempts": 1,  "input_tokens": 812,  "cache_read_tokens": 0,  "output_tokens": 143,  "usage_source": "provider",  "cost_micro": 489,  "ttft_ms": 190,  "duration_ms": 1420,  "stream": true,  "byok": false,  "zdr": false,  "logged": true,  "app_id": "chatbot",  "user_hash": "",  "cell": "in1",  "dialect_in": "openai",  "upstream_model": "gpt-5-mini",  "price_version_id": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01",  "upstream_ttft_ms": 186,  "gw_overhead_ms": 4,  "bytes_in": 2048,  "bytes_out": 1536,  "tool_calls": 0,  "has_images": false,  "has_tools": false,  "has_schema": false,  "cache_write_tokens": 0,  "reasoning_tokens": 0,  "tags": {    "env": "prod"  },  "user_agent": "openai-python/1.60",  "client_ip_prefix": "203.0.113.0/24",  "route_trace": "",  "timing": {    "ttft_ms": 190,    "upstream_ttft_ms": 186,    "duration_ms": 1420,    "gw_overhead_ms": 4  },  "usage": {    "source": "provider",    "normalised": {      "input_tokens": 812,      "output_tokens": 143,      "cache_read_tokens": 0,      "cache_write_tokens": 0,      "reasoning_tokens": 0    }  },  "attempt_rows": [    {      "attempt": 1,      "ts": "2026-09-10 11:59:00.130",      "provider": "openai",      "endpoint_id": "ep_openai_gpt-5-mini_us",      "pool_id": "pool_openai",      "key_hint": "sk-…9x",      "outcome": "ok",      "http_status": 200,      "error_class": "",      "ttft_ms": 186,      "duration_ms": 1410,      "output_tokens": 143    }  ],  "payload_state": "available",  "request": {    "model": "openai/gpt-5-mini",    "messages": [      {        "role": "user",        "content": [          {            "type": "text",            "text": "hi"          }        ]      }    ]  },  "response": {    "candidates": [      {        "index": 0,        "content": [          {            "type": "text",            "text": "Hello! How can I help?"          }        ],        "stop": {          "reason": "end_turn"        }      }    ],    "usage": {      "input_tokens": 812,      "output_tokens": 143,      "cache_read_tokens": 0,      "cache_write_tokens": 0,      "reasoning_tokens": 0    },    "cost": {      "total_micro_usd": 489,      "lines": [        {          "kind": "input",          "units": 812,          "unit_price_nano": 250,          "micro_usd": 203        },        {          "kind": "output",          "units": 143,          "unit_price_nano": 2000,          "micro_usd": 286        }      ],      "price_version": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01"    }  }}
GET
/v1/usage/savings
AuthorizationBearer <token>

In: header

Query Parameters

range?unknown
Default"30d"

Value in

  • "24h"
  • "7d"
  • "30d"
  • "90d"
project_id?string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/usage/savings"
{  "object": "usage_savings",  "range": {    "from": "2026-09-09T12:00:00Z",    "to": "2026-10-09T12:00:00Z"  },  "cost_micro": 5800000,  "saved_micro": 1450000,  "response_cache": {    "requests": 840,    "saved_micro": 310000  },  "prompt_cache": {    "requests": 2100,    "saved_micro": 240000  },  "model_routing": {    "requests": 3600,    "saved_micro": 900000  }}
GET
/v1/usage/statement
AuthorizationBearer <token>

In: header

Query Parameters

month?string
Match^\d{4}-\d{2}$
from?string
Formatdate-time
to?string
Formatdate-time
member?string
format?unknown
Default"json"

Value in

  • "json"
  • "csv"
  • "pdf"

Response Body

application/json

curl -X GET "https://example.com/v1/usage/statement"
{  "object": "usage_statement",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0ORG01",  "org_name": "Acme",  "billing_currency": "INR",  "from": "2026-10-01T00:00:00Z",  "to": "2026-11-01T00:00:00Z",  "generated_at": "2026-11-01T06:00:00Z",  "balance": {    "opening_micro": 4200000,    "closing_micro": 6950000,    "paid_micro": 10000000,    "payments": [      {        "topup_id": "top_01J9ZK2K4Q7Q3M3QX1V0TOP01",        "paid_at": "2026-10-03T08:00:00Z",        "currency": "INR",        "amount_minor": 100000,        "credits_micro": 10000000,        "document": "AIMLR/26-27/000012",        "document_kind": "receipt",        "tax_invoice": "INV-2026-0042",        "status": "paid"      }    ],    "usage_micro": 7250000,    "other": [],    "adjustments": []  },  "usage": {    "requests": 1820,    "input_tokens": 2450000,    "output_tokens": 310000,    "cache_read_tokens": 120000,    "reasoning_tokens": 0,    "charged_micro": 7250000,    "ledger_micro": 7250000,    "difference_micro": 0,    "members": [      {        "member_id": "usr_01J9ZK2K4Q7Q3M3QX1V0USER1",        "email": "[email protected]",        "requests": 1820,        "input_tokens": 2450000,        "output_tokens": 310000,        "cache_read_tokens": 120000,        "reasoning_tokens": 0,        "charged_micro": 7250000,        "keys": [          {            "key_id": "key_01J9ZK2K4Q7Q3M3QX1V0KEY01",            "name": "production",            "hint": "AbC12345",            "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0PRJ01",            "project_name": "Default",            "status": "active",            "requests": 1820,            "input_tokens": 2450000,            "output_tokens": 310000,            "cache_read_tokens": 120000,            "reasoning_tokens": 0,            "charged_micro": 7250000,            "models": [              {                "model": "openai/gpt-5-mini",                "requests": 1820,                "input_tokens": 2450000,                "output_tokens": 310000,                "cache_read_tokens": 120000,                "reasoning_tokens": 0,                "charged_micro": 7250000              }            ]          }        ]      }    ]  }}
GET
/v1/usage
AuthorizationBearer <token>

In: header

Query Parameters

range?unknown
Default"24h"

Value in

  • "24h"
  • "7d"
  • "30d"
  • "90d"
  • "custom"
from?string
Formatdate-time
to?string
Formatdate-time
granularity?unknown

ranges over 30 d default to day; over 90 d force day

Value in

  • "hour"
  • "day"
group_by?unknown

Value in

  • "project"
  • "key"
  • "team"
  • "member"
  • "model"
  • "provider"
  • "byok"
  • "app"
  • "tag"
tag?string

tag key for group_by=tag

compare?boolean
project_id?string
key_id?string
model?string
provider?string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/usage"
{  "object": "usage",  "range": {    "from": "2026-09-09T12:00:00Z",    "to": "2026-09-10T12:00:00Z",    "granularity": "hour"  },  "group_by": "model",  "totals": {    "requests": 12000,    "ok": 11930,    "errors": 70,    "input_tokens": 9600000,    "output_tokens": 1700000,    "cache_read_tokens": 400000,    "cache_write_tokens": 0,    "reasoning_tokens": 0,    "cost_micro": 5800000  },  "series": [    {      "requests": 12000,      "ok": 11930,      "errors": 70,      "input_tokens": 9600000,      "output_tokens": 1700000,      "cache_read_tokens": 400000,      "cache_write_tokens": 0,      "reasoning_tokens": 0,      "cost_micro": 5800000,      "bucket": "2026-09-10T11:00:00Z"    }  ],  "groups": [    {      "requests": 12000,      "ok": 11930,      "errors": 70,      "input_tokens": 9600000,      "output_tokens": 1700000,      "cache_read_tokens": 400000,      "cache_write_tokens": 0,      "reasoning_tokens": 0,      "cost_micro": 5800000,      "key": "openai/gpt-5-mini"    }  ]}