API reference

Export API

Read-only REST API for pulling your analytics into a warehouse, BI tool or script.

Authentication

Create a team API key under Account settings → API keys and send it as a bearer token. Keys are scoped to one team. They read everything and can start evals (POST /sites/:id/evals/run); they can't change settings.

curl https://agentstats.io/api/v1/sites \
  -H "Authorization: Bearer al_sk_…"

Conventions

  • Base URL: https://agentstats.io/api/v1
  • CSV: add ?format=csv to any list endpoint.
  • Range: range is one of today (since midnight in the project's timezone), 1h, 12h, 24h, 3d, 7d, 14d, 30d or 90d. Default 7d.
  • Filters: overview, tools, errors and sessions also take country (ISO code, or cloud for AI providers' servers and CI), agent (a client name such as claude-code) and agentType (coding, assistant, browser, human, ci or other).
  • Source: a project's tool calls come from its website (WebMCP), its MCP servers and its CLIs. Overview, tools, errors, sessions, events and schema take source=web or source=<MCP server or CLI id> to cover one of them; without it they cover the whole project. Per-tool rows always include their source, since two sources can have a tool of the same name.
  • Pagination: cursor-based with before and limit. Keep requesting with before=<last id> until a page has fewer rows than limit.

Endpoints

Account

GET /api/v1

Who the key belongs to, plus the list of endpoints.

Sites

GET /api/v1/sites

Every project in the team, with its id. Use that id in the endpoints below.

Overview

GET /api/v1/sites/{id}/overview?range=30d

Totals, trend and top tools for the range.

Tools

GET /api/v1/sites/{id}/tools?range=7d
GET /api/v1/sites/{id}/tools/{tool}

Per-tool call counts, error rates and latency. The second form returns one tool in detail.

Errors

GET /api/v1/sites/{id}/errors

Failed tool calls, grouped.

Sessions

GET /api/v1/sites/{id}/sessions?limit=100&before={iso}
GET /api/v1/sites/{id}/sessions/{session_id}

Agent sessions, newest first. The second form returns every event in one session.

Events

GET /api/v1/sites/{id}/events?limit=1000&before={id}&since={iso}&until={iso}

The bulk-export endpoint: raw events, newest first. Optional filters: type (e.g. tool_call), tool, status (e.g. error) and session.

Retention follows your plan. To keep a full history, sync at least as often as your retention window.

Schema

GET /api/v1/sites/{id}/schema

The current tool surface: names, descriptions, input schemas and annotations.

Alerts

GET /api/v1/sites/{id}/alerts?limit=100

Schema changes, new and removed tools, and error spikes.

Visitors

GET /api/v1/sites/{id}/visitors?range=30d
GET /api/v1/sites/{id}/visitors?range=30d&ref=ChatGPT&page=/pricing
GET /api/v1/sites/{id}/visitors?range=30d&format=csv&breakdown=sources

The people on the website, from Visitors: totals with the previous period, the series, sources, UTM tags, top, entry and exit pages, countries, devices and goals. Filter with the dashboard's parameters: page, ref (source, (none) for direct), utm_medium, utm_source, utm_campaign, country, device, browser, os and goal. With ?format=csv you get the series, or one breakdown with breakdown=sources, utm_medium, utm_source, utm_campaign, pages, entry_pages, exit_pages, countries, devices, browsers, os or goals.

Traffic

GET /api/v1/sites/{id}/traffic?range=30d

Human visitors vs. agent sessions. With ?format=csv you get the daily series. Human numbers come from Visitors once the site sends pageviews, else from an analytics tool connected before imports were paused. searchClicks adds up Google Search Console and Bing Webmaster Tools, and searchEngines splits them (Search engines & SEO).

Days and chart buckets everywhere in the API start at midnight in the project's timezone (Project settings → General); timestamps are ISO 8601 in UTC.

AI bots

GET /api/v1/sites/{id}/bots?range=7d&scope=ai
GET /api/v1/sites/{id}/bots/hits?limit=200&before={id}

A summary of AI crawler and agent traffic. scope is ai (default) or all. The hits form returns individual requests and accepts product, agent, kind (bot or referral), verified and format=csv.

AI visibility

GET /api/v1/sites/{id}/visibility
GET /api/v1/sites/{id}/visibility?run={run_id}

What ChatGPT, Claude, Gemini, Perplexity and Google AI Mode say about the product: the profile, its runs, and the results of the latest finished run (or the one run names).