Skip to Content
agent-stats

Local JSON API

Query the local report, model and tool series, sessions, requests, prompts, and quota observations.

Start agent-stats serve --all, then query the loopback server.

curl -fsS 'http://127.0.0.1:7373/api/report?since=7d&harness=codex&project=all'
curl -fsS 'http://127.0.0.1:7373/api/activity-series?kind=models&since=7d&project=all'
curl -fsSG 'http://127.0.0.1:7373/api/requests' \
  --data-urlencode 'model=example' --data-urlencode 'provider=provider-a' \
  --data-urlencode 'limit=25'

The API also works with a binary built without the browser interface. Use agent-stats query to read the existing index directly from a script or coding agent.

Usage and relationships

GET routeWhat it returns
/api/reportUsage totals and breakdowns, daily activity, hourly activity for short periods, and estimated cost and cache information where available.
/api/activity-seriesDated activity buckets. Pass kind=models for model and provider, or kind=tools for tool and MCP server. Uses hourly buckets through 72 hours, daily through 120 days, and monthly for longer periods or all time.
/api/model-activityDaily activity and available timings for the exact model supplied.
/api/tool-modelsCalls linked to the invoking model and provider when Pi or oh-my-pi recorded enough evidence.
/api/related-sessionsSessions behind kind and value. Kinds are day, harness, model, folder, agent, tool, and mcp. A tool may include server. An MCP relation takes itemHarness, itemScope, and itemOrigin from a local catalog entry. Accepts limit and offset.

Sessions, requests, and prompts

GET routeWhat it returns
/api/sessionsSessions ordered by latest activity. Counts and totals cover every matching session. Accepts limit and offset.
/api/sessions/{id}Usage, models, tools, parent and fork links when available, subagents, and prompt previews for a session.
/api/requestsModel calls across sessions, newest first, with hasMore. Accepts limit, offset, failed=1, q, and an exact model and provider. Omitting provider with a model selects calls with an unknown provider.
/api/sessions/{id}/requestsThe request journal scoped to one session. Accepts the same request filters.
/api/errorsLocally available error signatures and counts. Use the returned key as signature on a local requests route. Accepts limit.
/api/sessions/{id}/traceIndexed prompts, model calls, tool calls, and their agent context in time order. Accepts limit and offset and returns hasMore.
/api/promptsFlagged prompts, recurring requests, and totals by folder. limit and offset affect only the flagged list.
/api/prompts/model-signalsPrompt and flagged-prompt counts grouped by associated model and provider.
/api/sessions/{id}/prompts/{position}Full text of one prompt on the local server. Pass the position and optional revision from a preview. A stale revision returns 409.

Encode the entire session ID as one path segment, including any slash in the ID. For example, codex:run/agent becomes codex%3Arun%2Fagent.

Catalog, quotas, and server state

GET routeWhat it returns
/api/catalogInstalled catalog entries and recorded usage. Pass unused=true for enabled items with zero observed use.
/api/quotasCurrent account quota observations from available providers. A successful observation also contributes to the stored history.
/api/quotas/historyUp to 1,000 observations from the last 30 days, newest first.
/api/metaAvailable coding agents, current project, and default filters.
/api/syncBackground indexing state and counts, including skipped files.

Catalog, quotas, full prompt text, and detailed error messages require a loopback server without --allow-remote. Privacy and remote access explains what a remote listener exposes.

Filters and pagination

Report and analysis routes generally accept since, harness, and project. Omit since for all time. Pass project=all or project=current when the server has a current project. Metadata, sync, and account quota routes have their own scope.

On paginated routes, limit accepts 1 to 1,000 and defaults to 100. Start at offset=0 and increase it by the page size. Follow hasMore on requests and traces, or use count on session, related-session, and prompt lists. The selected index can change between requests during background indexing.

Unknown or repeated parameters return 400. Unknown or out-of-scope session IDs return 404. Errors use application/problem+json.

Refresh the index

POST /api/sync starts indexing or returns the run already in progress. It expects a same-origin browser request with no body or query string. Use Re-index in the dashboard to trigger it.

On this page