---
title: "Analytics API - Tracwell docs"
description: "Query Tracwell reports over HTTP with an API key, using the same tools and numbers as the dashboard and MCP."
canonical: "https://tracwell.app/docs/api"
markdown: "https://tracwell.app/docs/api.md"
---

# 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](https://tracwell.app/docs/agents) .

## 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

```bash
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

```json
{
  "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

```bash
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](https://tracwell.app/docs/agents#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

```json
{
  "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.