aiml docs
ReferenceAPI reference

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
cursor?string

Response Body

application/json

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
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"
  • "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"    }  ]}