API Reference

The Antlytics API lets you read analytics data and manage sites, goals, and funnels programmatically — useful for dashboards, automations, and AI tool integrations.

Base URL: https://www.antlytics.com/api/v1

OpenAPI: machine-readable spec at /openapi.json (OpenAPI 3.1). Use it with code generators, API clients, and AI assistants.

Authentication

All requests require an API token in the Authorization header:

Authorization: Bearer ant_<your-token>

Create tokens in Settings → API tokens. Each token is shown once — copy it to a secure location immediately.

Plan requirements

The REST API is available on paid plans (Starter and Pro, including the 14-day trial). Requests from a free-plan account return:

{ "error": "The REST API and MCP server require a paid plan. Upgrade in Settings → Billing." }

with status 403 Forbidden.

Rate limits

60 requests per minute per token. Exceeded requests receive 429 Too Many Requests with a Retry-After header.

Endpoints

Metric naming

Across REST responses, visitors and sessions mean visits (distinct session_id / tab sessions with a 30-minute idle timeout). They are not Unique visitors. The dashboard and MCP get_stats expose Unique visitors separately as unique_visitors (daily salted hash). Prefer the dashboard or MCP when you need that split. See Dashboard overview and Privacy behaviour.

GET /v1/stats

Summary statistics for a site over a time range.

Query parameters:

Response:

{
  "visitors": 1240,
  "pageviews": 3820,
  "bounce_rate": 42,
  "sessions": 1240
}

visitors and sessions are the same visit count (compatibility aliases).

Example:

curl "https://www.antlytics.com/api/v1/stats?site_id=YOUR_SITE_ID&from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/pages

Top pages by pageviews for a site.

Query parameters:

Response:

[
  { "path": "/", "pageviews": 1820, "visitors": 940 },
  { "path": "/pricing", "pageviews": 410, "visitors": 310 }
]

Example:

curl "https://www.antlytics.com/api/v1/pages?site_id=YOUR_SITE_ID&limit=5" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/referrers

Top referrers by visit count for a site.

Query parameters:

Response:

[
  { "referrer": "google.com", "visits": 620 },
  { "referrer": "reddit.com", "visits": 180 }
]

Example:

curl "https://www.antlytics.com/api/v1/referrers?site_id=YOUR_SITE_ID" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/utm

UTM source, medium, and campaign breakdown for a site. Only events with a utm_source are included.

Query parameters:

Response:

[
  { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "launch", "visitors": 340, "pageviews": 520 },
  { "utm_source": "twitter", "utm_medium": "social", "utm_campaign": null, "visitors": 120, "pageviews": 180 }
]

Example:

curl "https://www.antlytics.com/api/v1/utm?site_id=YOUR_SITE_ID" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/countries

Visitors and pageviews grouped by country (ISO 3166-1 alpha-2). Only events with a country value are included.

Query parameters:

Response:

[
  { "country": "AU", "visitors": 480, "pageviews": 920 },
  { "country": "US", "visitors": 310, "pageviews": 580 }
]

Example:

curl "https://www.antlytics.com/api/v1/countries?site_id=YOUR_SITE_ID&limit=10" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/devices

Visitors and pageviews grouped by device type (desktop, mobile, tablet). Only events with a device value are included.

Query parameters:

Response:

[
  { "device": "desktop", "visitors": 620, "pageviews": 1240 },
  { "device": "mobile", "visitors": 380, "pageviews": 560 }
]

Example:

curl "https://www.antlytics.com/api/v1/devices?site_id=YOUR_SITE_ID" \
  -H "Authorization: Bearer ant_YOUR_TOKEN"

GET /v1/events

Custom event counts grouped by event name.

Query parameters:

Response:

[
  { "name": "signup", "events": 42, "sessions": 38 },
  { "name": "cta_click", "events": 18, "sessions": 15 }
]

GET /v1/sites

List all sites owned by the API token user.

Response:

[
  {
    "id": "…",
    "name": "My app",
    "url": "https://example.com",
    "tracking_id": "…",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

POST /v1/sites

Create a site. Free accounts are limited to one site; paid plans have unlimited sites.

Body: { "name": "My app", "url": "https://example.com" }

Response: 201 with the created site object (same shape as list).

GET /v1/goals

List conversion goals for a site.

Query parameters: site_id (required)

Response:

[
  {
    "id": "…",
    "site_id": "…",
    "name": "Signup",
    "path_pattern": "/thank-you",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

POST /v1/goals

Create a conversion goal.

Body: { "site_id": "…", "name": "Signup", "path_pattern": "/thank-you" }

path_pattern must start with /.

Response: 201 with the created goal.

GET /v1/funnels

List funnels for a site.

Query parameters: site_id (required)

Response:

[
  {
    "id": "…",
    "site_id": "…",
    "name": "Signup",
    "steps": [
      { "type": "path", "value": "/pricing" },
      { "type": "path", "value": "/thank-you" }
    ],
    "created_at": "2024-01-01T00:00:00Z"
  }
]

POST /v1/funnels

Create a funnel with 2–8 ordered steps (type: path or event).

Body:

{
  "site_id": "…",
  "name": "Signup",
  "steps": [
    { "type": "path", "value": "/pricing" },
    { "type": "event", "value": "checkout_complete" }
  ]
}

Response: 201 with the created funnel.

GET /v1/funnels/:id/results

Compute ordered step progression for a funnel. When from/to are omitted, defaults to the last 7 days.

Query parameters: from, to (optional ISO 8601)

Response:

{
  "id": "…",
  "name": "Signup",
  "site_id": "…",
  "period": { "from": "…", "to": "…" },
  "result": {
    "overallConversion": 42,
    "steps": [
      {
        "step": { "type": "path", "value": "/pricing" },
        "sessions": 100,
        "conversionFromStart": 100,
        "conversionFromPrevious": 100
      }
    ]
  }
}

Error responses

All errors return JSON:

{ "error": "Unauthorized" }