API
Cost traces
Tag requests with a task id, list your tasks, and read back what each step cost, with an estimate of what one baseline model would have cost instead.
Tag the requests that make up one piece of work with a task id, then ask for the task's trace: which model ran each step, how many tokens it used, what it cost, and, if you name a baseline model, an estimate of what the whole task would have cost on that model alone.
Tag your requests
Add task_id, and optionally step_index, to each chat completion that belongs to the task:
curl https://backend.alfnrl.io/v1/chat/completions \
-H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openrouter/openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "List the line items on this invoice: ..."}],
"task_id": "invoice-run-914",
"step_index": 0
}'| Field | Type | |
|---|---|---|
task_id | string | Any string you choose. Requests with the same task_id form one task. |
step_index | integer | The request's position in the task. Steps are ordered by it, then by time. Optional, but send it: a request tagged with task_id alone is recorded as step_index: -1 and sorts before step 0. |
Both travel to the gateway as request metadata, which is how the usage is linked back to the task. Sending either one replaces any metadata of your own on that request.
Read the trace
GEThttps://backend.alfnrl.io/v1/tasks/{task_id}/trace
| Query parameter | |
|---|---|
baseline | Optional. A model id to compare against, for example openrouter/anthropic/claude-opus-5. |
curl "https://backend.alfnrl.io/v1/tasks/invoice-run-914/trace?baseline=openrouter/anthropic/claude-opus-5" \
-H "Authorization: Bearer $ALPHANEURAL_API_KEY"{
"task_id": "invoice-run-914",
"steps": [
{
"step_index": 0,
"model": "openrouter/openai/gpt-4o-mini",
"provider": "openrouter",
"prompt_tokens": 1840,
"completion_tokens": 260,
"upstream_cost": "0.000432",
"charged": "0.0004752",
"cost_source": "provider_reported",
"billed": false,
"at": "2026-09-10T14:20:41.204Z"
},
{
"step_index": 1,
"model": "openrouter/anthropic/claude-haiku-4.5",
"provider": "openrouter",
"prompt_tokens": 2100,
"completion_tokens": 180,
"upstream_cost": "0.003",
"charged": "0.0033",
"cost_source": "provider_reported",
"billed": false,
"at": "2026-09-10T14:20:49.877Z"
}
],
"totals": {
"steps": 2,
"unpriced_steps": 0,
"prompt_tokens": 3940,
"completion_tokens": 440,
"upstream_cost": "0.003432",
"charged": "0.0037752"
},
"counterfactual": {
"baseline_model": "openrouter/anthropic/claude-opus-5",
"estimated_cost": "0.0307",
"estimated_saving": "0.027268",
"basis": "estimate: this task's token counts priced at the baseline model's rates. Token counts are not portable between models, so treat it as indicative, not a quote."
}
}Money fields are decimal numbers encoded as strings, in US dollars.
Steps
| Field | |
|---|---|
model, provider | What ran the step. |
prompt_tokens, completion_tokens | Tokens used, as reported for the request. |
upstream_cost | What the provider charged for the step, before our margin. |
charged | The step at the price we quote, margin included. |
cost_source | Where the cost came from: provider_reported (the provider's own figure), litellm_computed (worked out by the gateway from its price table), or unpriced (no cost could be determined). |
billed | Whether this record is the one your balance was debited from. Balances are currently debited by a separate meter, so this reads false for every step; the usage is still taken from your balance, and your wallet's balance history is the record of it. |
at | When the usage was recorded. |
totals sums the steps. unpriced_steps counts the steps with cost_source: "unpriced": those are steps whose cost was not captured, not free steps, so a total with unpriced steps understates the task.
The baseline estimate
counterfactual prices the task's total prompt and completion tokens at the baseline model's list price and compares the result with the task's upstream_cost. Both figures are before our margin.
It is left out when the baseline is unknown or has no price, and when it would not have cost more than what you actually spent. It is an estimate, and says so in basis: the same text is a different number of tokens on different models.
List your tasks
GEThttps://backend.alfnrl.io/v1/tasks
Every task_id with usage recorded under your account, most recently active first, each with the same totals its trace reports.
| Query parameter | |
|---|---|
limit | How many to return. Default 50, at most 200. A negative or non-numeric value gets 400 limit must be a non-negative integer. |
cursor | The next_cursor from the previous page, unchanged. Any other value gets 400. |
curl "https://backend.alfnrl.io/v1/tasks?limit=20" \
-H "Authorization: Bearer $ALPHANEURAL_API_KEY"{
"tasks": [
{
"task_id": "invoice-run-914",
"totals": {"steps": 2, "unpriced_steps": 0, "prompt_tokens": 3940, "completion_tokens": 440, "upstream_cost": "0.003432", "charged": "0.0037752"},
"started_at": "2026-09-10T14:20:41.204Z",
"last_active_at": "2026-09-10T14:20:49.877Z"
}
],
"has_more": false
}next_cursor is present only when has_more is true. The list is paged by cursor rather than offset because a task that is still running moves to the top between pages. An account with no tagged usage gets 200 with an empty tasks array.
Empty tasks
Usage is recorded from the gateway after each request completes, so a step can take a moment to appear. A task with nothing recorded yet, including a task_id you have never used, returns 200 with an empty steps array, zero totals and a note:
{
"task_id": "invoice-run-914",
"steps": [],
"totals": {"steps": 0, "unpriced_steps": 0, "prompt_tokens": 0, "completion_tokens": 0, "upstream_cost": "0", "charged": "0"},
"note": "no usage recorded for this task"
}Scope
A trace, and the task list, cover only your account's usage. Task ids are strings you choose and often end up in logs, so another account using the same task_id never sees your steps, and you never see theirs. Any of your keys can read your traces.
If cost tracing is switched off on the server, both endpoints answer 404 cost tracing is not enabled.