API tracking
Agents call APIs directly: ChatGPT agent from OpenAI's cloud, assistants fetching for a user, and code that Claude Code, Cursor or Codex writes and runs against your API. API tracking records the calls agents make (method, route pattern, status and duration) and counts every other call, so you see which routes agents rely on, where they fail more than other callers do, and what an agent did in one run.
Add an API
Open Project settings → Setup → APIs and add one (or tick API when you create the project). Each API has its own secret key (al_api_…). Keep it on the server, like the project's server key.
Add the middleware
API tracking is part of the server SDK, so it runs in the same frameworks as agent tracking. Pass apiKey:
import express from 'express'
import { createAgentStats } from '@agentstats/sdk/server'
const app = express()
const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
app.use(lens.express()) // before your routes
import { Hono } from 'hono'
import { createAgentStats } from '@agentstats/sdk/server'
const app = new Hono()
const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
app.use(lens.hono())
// app/api/users/[id]/route.ts: wrap each route handler and name its route
import { lens } from '@/lib/agentstats' // createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
export const GET = lens.wrapFetch(async (request, { params }) => {
// …
}, { route: '/api/users/[id]' })
// server/plugins/agentstats.ts
import { createAgentStats } from '@agentstats/sdk/server'
const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
export default defineNitroPlugin(lens.nitro())
// src/hooks.server.ts
import { createAgentStats } from '@agentstats/sdk/server'
const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
export const handle = lens.sveltekit()
// src/middleware.ts
import { createAgentStats } from '@agentstats/sdk/server'
const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY })
export const onRequest = lens.astro()
Set AGENTSTATS_API_KEY where the API runs. On an API-only server every request is an API call. If the same server also serves your website, pass both keys, createAgentStats({ serverKey, apiKey }): paths under /api and /v1, /v2… go to the API and everything else to agent tracking. Change that with apiRoutes, a RegExp or a function of the path.
Python and Go
from agentstats.api import ApiTracker, AgentStatsASGI, init_flask
tracker = ApiTracker() # AGENTSTATS_API_KEY
app = AgentStatsASGI(app, tracker) # FastAPI, Starlette: the matched route is used
init_flask(flask_app, tracker) # Flask
t := api.New(api.Options{}) // AGENTSTATS_API_KEY
http.ListenAndServe(":8080", api.Middleware(t)(mux)) // ServeMux patterns are used; chi: Options.RouteOf
Optional: tag calls from your API client
If you ship a client, SDK or CLI for your API, add the headers that tell your API a coding agent is making the call:
import { agentHeaders } from '@agentstats/cli/headers'
fetch(url, { headers: { ...agentHeaders(), authorization: `Bearer ${apiKey}` } })
The same helper exists as agent_headers() in agentstats.cli (Python), cli.AgentHeaders() (Go) and agentstats::cli::agent_headers() (Rust). agentHeaders() returns {} unless a coding agent runs the code, so your users' production apps send nothing. While Claude Code, Cursor, Codex, OpenCode and others run it, it returns X-AI-Agent (claude-code/2.1.316) and X-AI-Agent-Run. The run id is the same session id the CLI SDK uses for the agent's thread, so an agent's commands and API calls line up.
How a call is attributed
The middleware keeps a call when it carries one of these, strongest first. The dashboard checks each one again:
| Evidence | Example | Checked |
|---|---|---|
| A Web Bot Auth signature | ChatGPT agent, Browserbase | The signature, against the agent's published keys |
| An agent's user agent | Claude-User, ChatGPT-User, Perplexity-User | The agent's published IP ranges |
An X-AI-Agent header | agentHeaders() in your client | Not provable: a hint, like the CLI's |
| A credential you name | Your OAuth client for Claude | You decide, in apiCaller |
Signatures and user agents that fail their check are counted as other calls, not stored. A call with none of these, including code an agent wrote that doesn't send the header, plain curl and every person's or app's call, is only counted per day, so you can see what share of your API traffic comes from agents.
Sessions
A session is one agent run: the run id agentHeaders() sends, or else the same caller and agent with no gap of 30 minutes. The caller is your request's credential (Authorization, X-API-Key or API-Key), sent as an HMAC keyed with your API key: the credential itself never leaves your server. If callers authenticate some other way, say who the caller is:
createAgentStats({
apiKey: process.env.AGENTSTATS_API_KEY,
// An API key id, an OAuth client and user… `{ id, agent }` names the agent behind a credential.
apiCaller: header => (header('x-client-id') === CLAUDE_CLIENT ? { id: CLAUDE_CLIENT, agent: 'claude-ai' } : header('x-client-id')),
})
apiCaller: false turns grouping by caller off.
Routes
Calls are recorded by route pattern, GET /api/users/:id, never by path. Express, Hono, Nitro, SvelteKit and Astro report the matched route; Next.js route handlers name it in wrapFetch. Where no pattern is known, values in the path (numbers, UUIDs, long tokens, emails) are replaced by :id.
What leaves your server
For an agent's call: method, route pattern, status, duration, the user agent, the X-AI-Agent headers, the caller's HMAC, and, only to verify the agent, its IP and signature headers (discarded once checked). For every other call: a count per day. Never request or response bodies, query strings, cookies or credentials.
Overhead
The middleware decides synchronously and sends batches in the background: agents' calls go out every 5 seconds or 100 calls, never on the request's path. Measured on an Express route doing no work at all, at saturation, it adds about 4 µs of CPU to a call no agent made and about 7 µs to an agent's call, against a millisecond or more for a typical handler.