Analytics API

Query your reports over HTTP with an API key. The API returns the same numbers as the dashboard and your AI assistant.

How it works

The Analytics API is the MCP endpoint, https://tracwell.app/mcp, called directly. Send one JSON-RPC 2.0 request per call with a tools/call method; there is no session to open first. Every tool on this page is also available to AI assistants.

Authenticate

Create a key in Settings → MCP → API keys with Read analytics permission, then send it on every request:

Required headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

API keys are secrets. Keep them in a server environment variable or CI secret, never in browser code. The API needs an active plan, including trials, and allows 300 requests per minute per key.

Find your website ID

Most tools need a projectId, the website ID. List the websites your key can read:

Terminal

curl https://tracwell.app/mcp \
  --header "Authorization: Bearer $TRACWELL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "analytics_projects", "arguments": {} }
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "permission": "read",
      "projects": [{
        "id": "YOUR_WEBSITE_ID",
        "name": "example.com",
        "collectionMode": "private",
        "status": "active"
      }],
      "nextCursor": null
    },
    "content": [{ "type": "text", "text": "..." }]
  }
}

The result is in result.structuredContent. The same website ID is shown in Settings → Website → Tracking setup. If nextCursor is not null, pass it back as cursor to get the next page.

Run a report

Report tools take a date range. from and to are calendar dates and both are included; timezone is an IANA name such as America/New_York.

Terminal

curl https://tracwell.app/mcp \
  --header "Authorization: Bearer $TRACWELL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "analytics_overview",
      "arguments": {
        "projectId": "YOUR_WEBSITE_ID",
        "from": "2026-10-01",
        "to": "2026-10-31",
        "timezone": "Europe/London"
      }
    }
  }'

To see every tool with its exact input and output schema, send {"jsonrpc": "2.0", "id": 3, "method": "tools/list"} with the same headers.

Read tools

Available with any key

analytics_projects: Websites the key can access, with their IDs. Start here.
analytics_overview: Traffic metrics, trend and breakdowns for a date range.
analytics_acquisition: Sources, mediums, campaigns and landing pages.
analytics_events: Event names and recent events, filterable by name and property.
analytics_event_detail: Property values and breakdowns for one event.
analytics_journeys: Recorded sessions, paginated.
analytics_journey_detail: The ordered page views and events inside one session.
analytics_goals / analytics_goal: Saved goals, and the conversion report for one.
analytics_funnels / analytics_funnel: Saved funnels, and the conversion report for one.
analytics_revenue: Revenue totals and attribution breakdowns.
notes_list: Chart notes for a website.

Keys with Read and manage goals / funnels permission can also preview, create and update goals and funnels, and add chart notes. Every write needs a UUID requestId; see Discover, preview, save.

Errors

A missing or revoked key returns HTTP 401. A notes-only key or an inactive plan returns 403. Errors inside a tool, such as an unknown website or the rate limit, return HTTP 200 with isError: true:

Tool error

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "RATE_LIMITED",
        "message": "Too many analytics requests.",
        "retryable": true
      }
    }
  }
}

Retry only when retryable is true, with backoff.