Report agent usage
report_agent_usageRecord what one agent run cost an issue (local or mirrored/upstream): tokens by kind and machine time — and which model did the work: 'model' with its 'role' (plan, code, review…), or 'models' for several, each named as you know it ('opus-5.5' and 'claude-opus-5-5' are one model; any name is kept) and 'via' for a router such as openmath. Send the model when the run starts, with 'startedAt' and no 'endedAt', and the issue shows it at work now; the report that ends the run may leave the models out — they stay, closed with the run. Re-sending the same 'source' + 'externalId' updates that record instead of adding a second one, so a retry never doubles the spend. Omit a metric you did not measure — omitted is 'not reported', which is different from zero. Requires permission to edit the issue.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"key": "<key>",
"source": "<source>",
"externalId": "<externalId>"
},
"name": "report_agent_usage"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| via | No | The router 'model' was reached through, e.g. 'openmath' (Open Math OS). Leave out for a model reached directly. | |
| host | No | Which host it ran on. | |
| note | No | Short note, e.g. the outcome. | |
| role | No | The part 'model' played in this run: plan, code, review, test, research — or another short word. | |
| agent | No | Which agent did the work, e.g. 'claude-code'. | |
| model | No | Which model it ran on, e.g. 'claude-opus-5'. | |
| runId | No | The run this record belongs to, when one run reports several records (different models or hosts). | |
| models | No | Several models this run used, each with its own part — instead of 'model'. The issue lists them under 'models' (get_issue). | |
| source | Yes | Who is reporting, e.g. 'bg-agent-api'. Idempotency is scoped to it. | |
| costUsd | No | Cost in USD, if you know the rates that applied. | |
| endedAt | No | When the run ended (ISO 8601). | |
| startedAt | No | When the run started (ISO 8601). | |
| externalId | Yes | Your own key for this record (usually the run id). Re-sending it updates the record. | |
| inputTokens | No | Input (prompt) tokens. | |
| agentSeconds | No | Wall-clock seconds the run took. Machine time, not a worklog. | |
| outputTokens | No | Output (completion) tokens. | |
| cacheReadTokens | No | Cache-read tokens. | |
| cacheWriteTokens | No | Cache-write tokens. |