API reference

Ingest API

The raw endpoints the SDKs send to. Use them to send server-side events or build your own integration.

You only need these if you're not using the SDKs, for example to report tool calls from a backend or to forward logs from a platform without a built-in drain.

Events API

POST https://agentstats.io/api/ingest
Content-Type: text/plain

Authenticated with the site's public key in the body. Send the JSON as text/plain to avoid a CORS preflight request.

{
  "key": "al_pub_…",
  "session_id": "…",
  "sdk": "my-sdk/1.0.0",
  "events": [
    { "type": "tool_call", "id": "…", "ts": 1757900000000, "tool": "search_products", "status": "success", "duration_ms": 120, "args": { "q": "shoes" } }
  ]
}

Event types: tool_call, tool_registered, tool_unregistered, tools_snapshot and custom. The shapes match the browser SDK's events.

Hits API

POST https://agentstats.io/api/ingest/hits
Authorization: Bearer al_srv_…

Authenticated with the site's secret server key. If your tool can't set Authorization, send X-AgentStats-Key: al_srv_… instead.

{
  "hits": [
    { "ts": 1757900000000, "method": "GET", "url": "https://example.com/pricing", "status": 200, "ua": "GPTBot/1.2", "ip": "20.171.207.1", "referrer": null }
  ],
  "humans": { "2026-09-15": 1840 }
}
FieldNotes
hits[]One per request: ts, method, url, status, ua, ip, referrer, and optional headers (for Web Bot Auth signatures)
humansOptional. Human page views per UTC day, used for the AI share of traffic

The body can be JSON or gzipped JSON, up to 20 MB. The same endpoint also accepts Vercel log drains and Cloudflare Logpush directly. See Log drains.

Bot visits count against a separate monthly quota, set by your plan.

MCP API

The MCP server SDKs post to POST /api/ingest/mcp with the MCP server's secret key. Use it directly to report from a language without an SDK.

curl -X POST https://agentstats.io/api/ingest/mcp \
  -H 'Authorization: Bearer al_srv_…' -H 'Content-Type: application/json' \
  -d '{"events":[{"ts":1793534400000,"method":"tools/call","tool":"search_docs","durationMs":42.5,"isError":false,"clientName":"claude-code","clientVersion":"2.1.0","sessionId":"s1"}]}'
events
array
Up to 1000 per request. Each has method (required), ts (epoch ms), tool (for tools/call), durationMs, isError, errorMessage, clientName, clientVersion and sessionId.
catalog
object
Optional. { tools: [{ name, description, inputSchema }], serverInfo: { name, version }, instructions }, sent when the tool list changes. Drives the Schema page, change alerts and the description linter.
serverName
string
Optional and informational: the key decides which MCP server the events belong to.

Responds 202 { accepted, dropped }. Over the monthly quota, events are dropped and reason is quota_exceeded. A website's key is refused with 409.