Ingest API
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 }
}
| Field | Notes |
|---|---|
hits[] | One per request: ts, method, url, status, ua, ip, referrer, and optional headers (for Web Bot Auth signatures) |
humans | Optional. 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.
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"}]}'
method (required), ts (epoch ms), tool (for tools/call), durationMs, isError, errorMessage, clientName, clientVersion and sessionId.{ tools: [{ name, description, inputSchema }], serverInfo: { name, version }, instructions }, sent when the tool list changes. Drives the Schema page, change alerts and the description linter.Responds 202 { accepted, dropped }. Over the monthly quota, events are dropped and reason is quota_exceeded. A website's key is refused with 409.