Quick start
curl
Streams, response headers and the route trace from a shell.
Stream with the route trace
x-aiml-debug: 1 asks the gateway to explain its routing decision in the x-aiml-route-trace header. The script prints the x-aiml-* headers followed by the SSE frames.
set -eu
BASE="${AIML_BASE_URL:-https://api.ai.ml}"
curl -sS -N -D - "$BASE/v1/chat/completions" \
-H "Authorization: Bearer $AIML_API_KEY" \
-H "Content-Type: application/json" \
-H "x-aiml-debug: 1" \
-d "{\"model\":\"${AIML_MODEL:-openai/gpt-5-mini}\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}" \
| tr -d '\r' | grep -i -E '^x-aiml-|^data: ' | awk '/^[Xx]-/ { split($0, kv, ": "); printf "%s: %s\n", tolower(kv[1]), substr($0, length(kv[1]) + 3); next } { print }'A run looks like this (header names lower-cased by the script):
x-aiml-request-id: 01K4N4V8Z8W3Q0G8S4YV6D5V2M
x-aiml-provider: openai
x-aiml-model: openai/gpt-5-mini
x-aiml-region: us-east-1
x-aiml-attempts: 1
x-aiml-route-trace: openai:gpt-5-mini(us-east-1) score=0.97 ...
data: {"id":"01K4N4V8Z8W3Q0G8S4YV6D5V2M","object":"chat.completion.chunk",...}
data: [DONE]Look a request up afterwards
The request id from the headers resolves to the settled cost (from the ledger), timings and every upstream attempt (from analytics). This needs the read:usage scope.
set -eu
BASE="${AIML_BASE_URL:-https://api.ai.ml}"
CPAPI="${AIML_CPAPI_URL:-$BASE}"
RID=$(curl -sS -D - -o /dev/null "$BASE/v1/chat/completions" \
-H "Authorization: Bearer $AIML_API_KEY" -H "Content-Type: application/json" \
-d "{\"model\":\"${AIML_MODEL:-openai/gpt-5-mini}\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello\"}]}" \
| tr -d '\r' | awk 'tolower($1)=="x-aiml-request-id:" {print $2}')
echo "request_id=$RID"
sleep "${AIML_ANALYTICS_WAIT:-3}"
curl -sS "$CPAPI/v1/generation/$RID" -H "Authorization: Bearer $AIML_API_KEY"
echo{"id":"01K4N4V8Z8W3Q0G8S4YV6D5V2M","object":"generation","model":"openai/gpt-5-mini","status":"ok",
"usage":{"input_tokens":12,"output_tokens":9,"source":"provider"},
"cost":{"total_micro_usd":27,"price_version":"pv_01K4…"},
"timing":{"ttft_ms":184,"duration_ms":611},
"attempts":[{"provider":"openai","status":200,"ttft_ms":184}],
"source":{"cost":"ledger","timing":"analytics"}}source.cost is ledger when the request has settled; analytics can lag by a few seconds and the console shows a banner while it does.
Headers on every inference response
| Header | Meaning |
|---|---|
x-aiml-request-id | ULID; the id of the JSON body too |
x-aiml-provider, x-aiml-region | endpoint that served the request |
x-aiml-model | model as resolved (vendor/model) |
x-aiml-attempts | upstream attempts, including fallbacks |
x-aiml-cost-micro | settled cost in micro-USD (JSON responses; streams settle after the last frame) |
x-aiml-warnings | comma-separated warning codes, for example param_dropped, feature_degraded |
x-aiml-stop | on streams: the stop reason (end_turn, max_tokens, tool_use, budget_exceeded, timeout, error) |
x-aiml-route-trace | only with x-aiml-debug: 1 |