---
title: "API Overview"
description: "REST API reference for Sealmetrics — query analytics stats and manage sites, exports, and alerts with API key or JWT authentication"
canonical_url: "https://docs.sealmetrics.com/api"
lang: "en"
date_generated: "2026-08-09T18:18:16.203Z"
source_hash: "39a0c987193c5d31e7d89e282306ce418df55b5cb6a00ed991f016f20beb24e8"
content_type: "api-reference"
owner: "engineering"
llm_priority: "critical"
source_file: "api/index.mdx"
publisher: "Sealmetrics"
---

# API Overview

Canonical page: https://docs.sealmetrics.com/api

REST API for querying analytics data and managing your Sealmetrics account programmatically.

## At a glance

| | |
|---|---|
| **Base URL** | `https://my.sealmetrics.com/api/v1` (HTTPS only, JSON) |
| **Interactive reference** | **[docs.sealmetrics.com/api-reference](https://docs.sealmetrics.com/api-reference/)** |
| **OpenAPI 3.1 spec** | [`openapi.json`](https://docs.sealmetrics.com/openapi.json) · [`openapi.yaml`](https://docs.sealmetrics.com/openapi.yaml) — generate a client straight from it |
| **Authentication** | [API key](/api/api-tokens) (`X-API-Key`), [JWT bearer](/api/authentication), or [OAuth 2.1 + PKCE](/api/oauth) for third-party apps |
| **AI assistants** | Hosted MCP server at `https://mcp.sealmetrics.com/mcp` — [setup](/integrations/mcp-server) |
| **Building an agent?** | Start at **[For AI Agents](/api/for-agents)** |
| **Batch** | [Up to 50 queries in one request](/api/batch), with dependency ordering |
| **Long-running work** | [Async export jobs](/api/exports) with `export.completed` [webhooks](/api/webhooks) |
| **Headless signup** | [`POST /provision`](/api/provision) — create a free account from code |
| **Errors** | One envelope, stable `error.code` — [catalogue](/api/errors) |
| **Rate limits** | `X-RateLimit-*` on every response — [per-plan limits](/api/rate-limits) |

## Quick Start

```bash
curl -X GET "https://my.sealmetrics.com/api/v1/stats/overview?site_id=YOUR_SITE_ID&period=7d" \
  -H "X-API-Key: sm_your_api_key_here"
```

Response:

```json
{
  "success": true,
  "data": {
    "date_range": {
      "start_date": "2025-01-01",
      "end_date": "2025-01-07",
      "days": 7
    },
    "traffic": {
      "entrances": 12543,
      "engaged_entrances": 7234,
      "page_views": 28976,
      "microconversions": 892,
      "conversions": 156,
      "revenue": "12450.00",
      "bounce_rate": 42.3,
      "pages_per_session": 2.31
    },
    "conversions": {
      "conversions": 156,
      "revenue": "12450.00",
      "microconversions": 892,
      "conversion_rate": 1.24,
      "average_order_value": "79.81"
    }
  },
  "meta": {},
  "timestamp": "2025-01-08T00:00:00Z"
}
```

## API Sections

### Analytics Data

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/stats/overview` | GET | Dashboard overview with all key metrics |
| `/stats/pages` | GET | Page metrics with pagination |
| `/stats/mediums` | GET | Traffic by UTM medium |
| `/stats/sources` | GET | Traffic by UTM source |
| `/stats/campaigns` | GET | Traffic by UTM campaign |
| `/stats/terms` | GET | Traffic by UTM term |
| `/stats/contents` | GET | Traffic by UTM content |
| `/stats/referrers` | GET | Referrer domain traffic |
| `/stats/geo/countries` | GET | Geographic breakdown |
| `/stats/devices` | GET | Device, browser, OS breakdown |

### Multi-Site Aggregate (superadmin)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/stats/aggregate/overview` | GET | Portfolio overview across multiple sites |
| `/stats/aggregate/pages` | GET | Pages aggregated across sites |
| `/stats/aggregate/mediums` | GET | UTM mediums aggregated across sites |
| `/stats/aggregate/sources` | GET | UTM sources aggregated across sites |
| `/stats/aggregate/geo/countries` | GET | Countries aggregated across sites |
| `/stats/aggregate/devices` | GET | Devices aggregated across sites |
| `/stats/aggregate/landing-pages` | GET | Landing pages aggregated across sites |
| `/stats/aggregate/conversions` | GET | Conversions by type across sites |

See [Multi-Site Aggregate Stats](/api/stats-aggregate).

### Billing

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/billing/plans` | GET | List pricing plans (public) |
| `/billing/overview` | GET | Billing overview (subscription, usage, payment method) |
| `/billing/checkout` | POST | Create Stripe Checkout session |
| `/billing/portal` | POST | Create Stripe customer portal session |
| `/billing/subscription` | GET | Subscription details |
| `/billing/subscription/cancel` | POST | Schedule cancellation at period end |
| `/billing/subscription/resume` | POST | Undo a scheduled cancellation |
| `/billing/subscription/history` | GET | Subscription audit log |
| `/billing/invoices` | GET | List invoices |
| `/billing/usage/current` | GET | Current period event usage |
| `/billing/usage/history` | GET | Past period event usage |
| `/billing/overage-status` | GET | Overage history and forgiveness status |
| `/billing/coupons/validate` | POST | Validate a discount code |
| `/billing/accounting-email` | GET, PUT | Accounting email for invoices |
| `/billing/seal-ai/*` | POST | Seal AI Private add-on (subscribe, unsubscribe, token packs) |

See [Billing API](/api/billing).

### Site Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sites` | GET, POST | List and create sites |
| `/sites/{id}` | GET, PATCH, DELETE | Manage specific site |
| `/sites/{id}/domains` | GET, POST, DELETE | Authorized domains |
| `/sites/{id}/utm-mappings` | GET, POST, PATCH, DELETE | UTM parameter mappings |
| `/sites/{id}/pixel` | GET | Get tracking pixel code |
| `/sites/{id}/pixel/status` | GET | Check pixel installation |

### Organizations

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/organizations` | GET, POST | List and create organizations |
| `/organizations/{slug}` | GET, PATCH, DELETE | Manage specific organization |
| `/organizations/{slug}/members` | GET, POST, PATCH, DELETE | Team member management |
| `/organizations/{slug}/sites` | GET | List organization sites |
| `/organizations/{slug}/invitations` | GET, POST, DELETE | Manage invitations |

### Authentication

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/token` | POST | Login with email/password |
| `/auth/refresh` | POST | Refresh access token |
| `/auth/logout` | POST | Logout current session |
| `/auth/me` | GET | Get current user info |
| `/auth/sessions` | GET, DELETE | Manage active sessions |
| `/auth/forgot-password` | POST | Request password reset |
| `/auth/reset-password` | POST | Reset password with token |

### API Tokens

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api-tokens` | GET, POST | List and create API tokens |
| `/api-tokens/{id}` | GET, DELETE | Get or revoke token |
| `/api-tokens/scopes` | GET | List available scopes |

### OAuth 2.1 (third-party apps and AI assistants)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/.well-known/oauth-authorization-server` | GET | RFC 8414 discovery metadata (served at the host root) |
| `/oauth/register` | POST | Dynamic client registration (RFC 7591) |
| `/oauth/authorize` | GET | Start the authorization code + PKCE flow |
| `/oauth/token` | POST | Exchange a code, or refresh a token |
| `/oauth/revoke` | POST | Revoke a token (RFC 7009) |
| `/oauth/connections` | GET | List the user's active grants |
| `/oauth/connections/{grant_id}` | DELETE | Revoke one grant |

See [OAuth 2.1](/api/oauth).

### Provisioning

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/provision` | POST | Create a free-tier account headlessly (`X-Provision-Key` required) |

See [Provisioning](/api/provision).

### Segments

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/segments` | GET, POST | List and create saved segments |
| `/segments/{id}` | GET, PUT, DELETE | Manage specific segment |
| `/segments/{id}/duplicate` | POST | Duplicate a segment |

### Webhooks

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/webhooks` | GET, POST | List and create webhook endpoints |
| `/webhooks/{id}` | GET, PATCH, DELETE | Manage specific webhook |
| `/webhooks/{id}/test` | POST | Send test webhook |
| `/webhooks/{id}/rotate-secret` | POST | Rotate webhook secret |
| `/webhooks/{id}/deliveries` | GET | List delivery history |
| `/webhooks/event-types` | GET | List available event types |

### Alerts

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/alerts/rules` | GET, POST | List and create alert rules |
| `/alerts/rules/{id}` | GET, PATCH, DELETE | Manage alert rule |
| `/alerts/rules/{id}/test` | POST | Test alert rule |
| `/alerts/history` | GET | Get alert history |
| `/alerts/stats` | GET | Get alert statistics |

### Bulk Exports

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/exports` | GET, POST | List and create export jobs |
| `/exports/{id}` | GET, DELETE | Get or cancel export |
| `/exports/estimate` | POST | Estimate export size |
| `/exports/stream` | POST | Stream small export directly |
| `/exports/download/{token}` | GET | Download export file |

### BigQuery Integration

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/integrations/bigquery` | GET, POST, PATCH, DELETE | Configure BigQuery integration |
| `/integrations/bigquery/setup` | POST | Create BigQuery tables |
| `/integrations/bigquery/sync` | POST | Trigger manual sync |
| `/integrations/bigquery/backfill` | POST | Backfill historical data |
| `/integrations/bigquery/logs` | GET | List sync logs |
| `/integrations/bigquery/schema` | GET | Get table schema |

### IP Allowlist

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ip-allowlist/settings` | GET, PUT | Manage allowlist settings |
| `/ip-allowlist/patterns` | GET, POST | List and add IP patterns |
| `/ip-allowlist/patterns/{id}` | PATCH, DELETE | Manage specific pattern |
| `/ip-allowlist/patterns/bulk` | POST | Add multiple patterns |
| `/ip-allowlist/check` | POST | Validate an IP address |
| `/ip-allowlist/export` | GET | Export patterns |
| `/ip-allowlist/import` | POST | Import patterns |
| `/ip-allowlist/audit` | GET | Access audit log |

## Common Query Parameters

These parameters are available on most analytics endpoints:

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `site_id` | string | **Required.** Site identifier | `my-site` |
| `period` | string | Time period shortcut | `today`, `7d`, `30d`, `90d` |
| `start_date` | date | Start date (YYYY-MM-DD) | `2025-01-01` |
| `end_date` | date | End date (YYYY-MM-DD) | `2025-01-31` |
| `segment` | string | Apply saved segment filters | `paid-traffic` |
| `country` | string | Filter by country (ISO 2) | `ES`, `US` |
| `utm_source` | string | Filter by UTM source | `google` |
| `utm_medium` | string | Filter by UTM medium | `cpc` |
| `utm_campaign` | string | Filter by UTM campaign | `brand-2025` |
| `compare` | string | Comparison mode | `previous`, `yoy` |
| `page` | int | Page number (default: 1) | `1` |
| `page_size` | int | Results per page (default: 50) | `100` |
| `sort_by` | string | Sort field | `entrances`, `revenue` |
| `sort_order` | string | Sort direction | `asc`, `desc` |

### Period Shortcuts

| Value | Description |
|-------|-------------|
| `today` | Current day |
| `yesterday` | Previous day |
| `7d` | Last 7 days |
| `30d` | Last 30 days |
| `90d` | Last 90 days |
| `12m` | Last 12 months |
| `this_week` | Current week |
| `last_week` | Previous week |
| `this_month` | Current month |
| `last_month` | Previous month |
| `this_quarter` | Current quarter |
| `last_quarter` | Previous quarter |
| `this_year` | Current year |
| `last_year` | Previous year |
| `wtd` | Week to date |
| `mtd` | Month to date |
| `qtd` | Quarter to date |
| `ytd` | Year to date |

## Response Format

All successful responses wrap data in a `data` field:

```json
{
  "data": {
    // Response payload
  }
}
```

Paginated responses include pagination metadata:

```json
{
  "data": [...],
  "total": 156,
  "page": 1,
  "page_size": 50,
  "has_next": true,
  "has_prev": false
}
```

## Error Responses

All errors return JSON with this structure:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  },
  "request_id": "ae817c5b-82df-430f-83e6-10c937e4e5e4"
}
```

`error.code` is stable — branch on it. `error.message` is for humans and may change. `request_id` is also returned in the `X-Request-ID` header.

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `bad_request` | Invalid parameters |
| 401 | `unauthorized` | Missing or invalid authentication |
| 403 | `forbidden` | Valid auth but insufficient permissions |
| 404 | `not_found` | Resource does not exist |
| 409 | `conflict` | Resource already exists |
| 422 | `validation_error` | Schema validation failed; `error.detail` lists the fields |
| 429 | `rate_limit_exceeded` | Too many requests — honour `Retry-After` |
| 500 | `internal_error` | Server error |
| 503 | `database_unavailable` | Temporary — honour `Retry-After` |

Full list, including which codes are retryable: **[Error codes](/api/errors)**.

## Documentation

- [For AI Agents](/api/for-agents) - Everything an LLM or agent needs, on one page
- [Interactive API Reference](https://docs.sealmetrics.com/api-reference/) - Every endpoint, generated from the OpenAPI spec
- [Quick Start](/api/quick-start) - First API call in 5 minutes
- [Authentication](/api/authentication) - API keys and JWT tokens
- [OAuth 2.1](/api/oauth) - Connect third-party apps and AI assistants to other people's accounts
- [Provisioning](/api/provision) - Create a free-tier account headlessly
- [Error codes](/api/errors) - Every `error.code`, and what to retry
- [Stats Endpoints](/api/stats) - Analytics data endpoints
- [Multi-Dimensional Query](/api/stats-query) - Dimensions, metrics and filters in one request
- [Batch API](/api/batch) - Up to 50 queries per request
- [Multi-Site Aggregate Stats](/api/stats-aggregate) - Portfolio metrics across multiple sites
- [Billing API](/api/billing) - Plans, subscriptions, invoices, usage, Seal AI Private add-on
- [Sites](/api/sites) - Site management
- [Organizations](/api/organizations) - Team management
- [Segments](/api/segments) - Saved segments
- [Exports](/api/exports) - Asynchronous bulk data exports
- [Webhooks](/api/webhooks) - Webhook subscriptions
- [BigQuery Integration](/api/bigquery) - Export to Google BigQuery
- [IP Allowlist](/api/ip-allowlist) - Restrict access by IP
- [Rate Limits](/api/rate-limits) - Limits per plan tier
- [API FAQ](/api/faq) - Common integration questions (`account_id` vs `site_id`, event-level conversions, JWT scopes)