---
title: "Usage and metrics"
description: "Per-run token, tool, duration and cost metrics, and account-wide agent usage from GET /api/v1/usage and the developer dashboard."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/usage"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/usage.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Usage and metrics
URL: /developers/docs/agent-api/usage
LLM index: /llms.txt
Description: Per-run token, tool, duration and cost metrics, and account-wide agent usage from GET /api/v1/usage and the developer dashboard.
Related: agent-api, agent-api/runs, papers-api/limits

# Usage and metrics

Every agent run records what it used, whichever way it started: the website, the HTTP API (research or health), or MCP.

## Per-run metrics

A completed JSON response includes `metrics`, and so does every run from `GET /api/v1/runs/{run_id}` once it ends:

```json
{
	"input_tokens": 18240,
	"output_tokens": 1630,
	"total_tokens": 19870,
	"cached_input_tokens": 12000,
	"reasoning_tokens": 0,
	"tool_calls": 6,
	"continuations": 1,
	"duration_ms": 41200,
	"model": "provider/model-id",
	"models": ["provider/model-id"],
	"estimated_cost_usd": 0.0412
}
```

| Field                                           | Meaning                                                                                                                                                                                                |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `input_tokens`, `output_tokens`, `total_tokens` | Totals across every model call in the turn, including automatic continuations.                                                                                                                         |
| `cached_input_tokens`, `reasoning_tokens`       | Reported when the provider returns them, otherwise `0`.                                                                                                                                                |
| `tool_calls`                                    | Server-side tool calls the agent made.                                                                                                                                                                 |
| `continuations`                                 | Automatic continuations used to finish a long answer.                                                                                                                                                  |
| `model`, `models`                               | The model that finished the turn, and every model that took part (fallbacks included).                                                                                                                 |
| `estimated_cost_usd`                            | Model tokens priced at catalog rates for `model`. It does not include search, sandbox, or other tool costs, and it is `null` when the model has no published price. It is an estimate, not an invoice. |

The JSON response keeps its existing `usage` object (the provider's raw token counts) alongside `metrics`.

## Account usage

`GET /api/v1/usage` totals the API key owner's agent runs over a window, grouped as you choose:

```bash
curl "https://scholarxiv.com/api/v1/usage?range=30d&group_by=model" \
  -H "Authorization: Bearer sxv_your_key_here"
```

| Parameter  | Values                                               | Default |
| ---------- | ---------------------------------------------------- | ------- |
| `range`    | `24h`, `7d`, `30d`, `90d`                            | `7d`    |
| `group_by` | `day`, `model`, `surface`, `source`, `key`, `status` | `day`   |
| `surface`  | `research`, `health`                                 | all     |
| `source`   | `web`, `api`, `mcp`                                  | all     |
| `key_id`   | An API key id                                        | all     |

The response has `totals` and `groups`. Each has `runs`, `completed`, `failed`, `cancelled`, the token totals, `tool_calls`, `estimated_cost_usd`, and `avg_duration_ms`; each group also has its `key` (the day, model, surface, source, key id, or status).

Tag runs with `metadata` on the message (up to 16 string keys) to tell your own traffic apart. Metadata is stored on the run and on its usage row, and returned on the run.

The [Usage page](/developers/dashboard/usage) of the developer dashboard shows the same agent usage by source, surface, and model.

## Limits

Agent calls use the shared [API rate limits](/developers/docs/papers-api/limits). A POST retried with the same Idempotency-Key counts as a request but starts no new agent work. Reading, streaming, listing, and cancelling runs do not count against the hourly limit.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).