Skip to main content

API

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

At a glance​

Base URLhttps://my.sealmetrics.com/api/v1 (HTTPS only, JSON)
Interactive referencedocs.sealmetrics.com/api-reference
OpenAPI 3.1 specopenapi.json · openapi.yaml — generate a client straight from it
AuthenticationAPI key (X-API-Key), JWT bearer, or OAuth 2.1 + PKCE for third-party apps
AI assistantsHosted MCP server at https://mcp.sealmetrics.com/mcp — setup
Building an agent?Start at For AI Agents
BatchUp to 50 queries in one request, with dependency ordering
Long-running workAsync export jobs with export.completed webhooks
Headless signupPOST /provision — create a free account from code
ErrorsOne envelope, stable error.code — catalogue
Rate limitsX-RateLimit-* on every response — per-plan limits

Quick Start​

GET/stats/overview 
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:

{
  "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​

EndpointMethodDescription
/stats/overviewGETDashboard overview with all key metrics
/stats/pagesGETPage metrics with pagination
/stats/mediumsGETTraffic by UTM medium
/stats/sourcesGETTraffic by UTM source
/stats/campaignsGETTraffic by UTM campaign
/stats/termsGETTraffic by UTM term
/stats/contentsGETTraffic by UTM content
/stats/referrersGETReferrer domain traffic
/stats/geo/countriesGETGeographic breakdown
/stats/devicesGETDevice, browser, OS breakdown

Multi-Site Aggregate (superadmin)​

EndpointMethodDescription
/stats/aggregate/overviewGETPortfolio overview across multiple sites
/stats/aggregate/pagesGETPages aggregated across sites
/stats/aggregate/mediumsGETUTM mediums aggregated across sites
/stats/aggregate/sourcesGETUTM sources aggregated across sites
/stats/aggregate/geo/countriesGETCountries aggregated across sites
/stats/aggregate/devicesGETDevices aggregated across sites
/stats/aggregate/landing-pagesGETLanding pages aggregated across sites
/stats/aggregate/conversionsGETConversions by type across sites

See Multi-Site Aggregate Stats.

Billing​

EndpointMethodDescription
/billing/plansGETList pricing plans (public)
/billing/overviewGETBilling overview (subscription, usage, payment method)
/billing/checkoutPOSTCreate Stripe Checkout session
/billing/portalPOSTCreate Stripe customer portal session
/billing/subscriptionGETSubscription details
/billing/subscription/cancelPOSTSchedule cancellation at period end
/billing/subscription/resumePOSTUndo a scheduled cancellation
/billing/subscription/historyGETSubscription audit log
/billing/invoicesGETList invoices
/billing/usage/currentGETCurrent period event usage
/billing/usage/historyGETPast period event usage
/billing/overage-statusGETOverage history and forgiveness status
/billing/coupons/validatePOSTValidate a discount code
/billing/accounting-emailGET, PUTAccounting email for invoices
/billing/seal-ai/*POSTSeal AI Private add-on (subscribe, unsubscribe, token packs)

See Billing API.

Site Management​

EndpointMethodDescription
/sitesGET, POSTList and create sites
/sites/{id}GET, PATCH, DELETEManage specific site
/sites/{id}/domainsGET, POST, DELETEAuthorized domains
/sites/{id}/utm-mappingsGET, POST, PATCH, DELETEUTM parameter mappings
/sites/{id}/pixelGETGet tracking pixel code
/sites/{id}/pixel/statusGETCheck pixel installation

Organizations​

EndpointMethodDescription
/organizationsGET, POSTList and create organizations
/organizations/{slug}GET, PATCH, DELETEManage specific organization
/organizations/{slug}/membersGET, POST, PATCH, DELETETeam member management
/organizations/{slug}/sitesGETList organization sites
/organizations/{slug}/invitationsGET, POST, DELETEManage invitations

Authentication​

EndpointMethodDescription
/auth/tokenPOSTLogin with email/password
/auth/refreshPOSTRefresh access token
/auth/logoutPOSTLogout current session
/auth/meGETGet current user info
/auth/sessionsGET, DELETEManage active sessions
/auth/forgot-passwordPOSTRequest password reset
/auth/reset-passwordPOSTReset password with token

API Tokens​

EndpointMethodDescription
/api-tokensGET, POSTList and create API tokens
/api-tokens/{id}GET, DELETEGet or revoke token
/api-tokens/scopesGETList available scopes

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

EndpointMethodDescription
/.well-known/oauth-authorization-serverGETRFC 8414 discovery metadata (served at the host root)
/oauth/registerPOSTDynamic client registration (RFC 7591)
/oauth/authorizeGETStart the authorization code + PKCE flow
/oauth/tokenPOSTExchange a code, or refresh a token
/oauth/revokePOSTRevoke a token (RFC 7009)
/oauth/connectionsGETList the user's active grants
/oauth/connections/{grant_id}DELETERevoke one grant

See OAuth 2.1.

Provisioning​

EndpointMethodDescription
/provisionPOSTCreate a free-tier account headlessly (X-Provision-Key required)

See Provisioning.

Segments​

EndpointMethodDescription
/segmentsGET, POSTList and create saved segments
/segments/{id}GET, PUT, DELETEManage specific segment
/segments/{id}/duplicatePOSTDuplicate a segment

Webhooks​

EndpointMethodDescription
/webhooksGET, POSTList and create webhook endpoints
/webhooks/{id}GET, PATCH, DELETEManage specific webhook
/webhooks/{id}/testPOSTSend test webhook
/webhooks/{id}/rotate-secretPOSTRotate webhook secret
/webhooks/{id}/deliveriesGETList delivery history
/webhooks/event-typesGETList available event types

Alerts​

EndpointMethodDescription
/alerts/rulesGET, POSTList and create alert rules
/alerts/rules/{id}GET, PATCH, DELETEManage alert rule
/alerts/rules/{id}/testPOSTTest alert rule
/alerts/historyGETGet alert history
/alerts/statsGETGet alert statistics

Bulk Exports​

EndpointMethodDescription
/exportsGET, POSTList and create export jobs
/exports/{id}GET, DELETEGet or cancel export
/exports/estimatePOSTEstimate export size
/exports/streamPOSTStream small export directly
/exports/download/{token}GETDownload export file

BigQuery Integration​

EndpointMethodDescription
/integrations/bigqueryGET, POST, PATCH, DELETEConfigure BigQuery integration
/integrations/bigquery/setupPOSTCreate BigQuery tables
/integrations/bigquery/syncPOSTTrigger manual sync
/integrations/bigquery/backfillPOSTBackfill historical data
/integrations/bigquery/logsGETList sync logs
/integrations/bigquery/schemaGETGet table schema

IP Allowlist​

EndpointMethodDescription
/ip-allowlist/settingsGET, PUTManage allowlist settings
/ip-allowlist/patternsGET, POSTList and add IP patterns
/ip-allowlist/patterns/{id}PATCH, DELETEManage specific pattern
/ip-allowlist/patterns/bulkPOSTAdd multiple patterns
/ip-allowlist/checkPOSTValidate an IP address
/ip-allowlist/exportGETExport patterns
/ip-allowlist/importPOSTImport patterns
/ip-allowlist/auditGETAccess audit log

Common Query Parameters​

These parameters are available on most analytics endpoints:

ParameterTypeDescriptionExample
site_idstringRequired. Site identifiermy-site
periodstringTime period shortcuttoday, 7d, 30d, 90d
start_datedateStart date (YYYY-MM-DD)2025-01-01
end_datedateEnd date (YYYY-MM-DD)2025-01-31
segmentstringApply saved segment filterspaid-traffic
countrystringFilter by country: ISO-3166-1 alpha-2 code or Unknown — see belowES, US, Unknown
utm_sourcestringFilter by UTM sourcegoogle
utm_mediumstringFilter by UTM mediumcpc
utm_campaignstringFilter by UTM campaignbrand-2025
comparestringComparison modeprevious, yoy
pageintPage number (default: 1)1
page_sizeintResults per page (default: 50)100
sort_bystringSort fieldentrances, revenue
sort_orderstringSort directionasc, desc

Filtering by country​

country takes an ISO-3166-1 alpha-2 code (ES, US, DE, case-insensitive) or the literal Unknown, and never a country name. Any other value returns 422 validation_error naming the parameter, for example country=Spain:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "detail": [
      {"field": "query.country", "message": "String should match pattern '^(?i:[a-z]{2}|unknown)$'", "type": "string_pattern_mismatch"}
    ]
  }
}

The check is on format: two letters, or Unknown. A well-formed code with no traffic, such as XX or a country that never visited, returns empty results, not an error.

Earlier, an invalid value was ignored by some endpoints (they returned unfiltered totals) and caused a 500 on others. On endpoints that accept the parameter repeated (?country=ES&country=FR), each value is validated, and a malformed one is no longer dropped silently.

Unknown is the value stored when the visitor's browser timezone maps to no country. The country always comes from the timezone, never from the IP address; see country detection. country=Unknown isolates that traffic. To see which codes have traffic, call GET /stats/geo/countries.

device_type follows the same rule: desktop, mobile or tablet (case-insensitive), and any other value returns 422.

Period Shortcuts​

ValueDescription
todayCurrent day
yesterdayPrevious day
7dLast 7 days
30dLast 30 days
90dLast 90 days
12mLast 12 months
this_weekCurrent week
last_weekPrevious week
this_monthCurrent month
last_monthPrevious month
this_quarterCurrent quarter
last_quarterPrevious quarter
this_yearCurrent year
last_yearPrevious year
wtdWeek to date
mtdMonth to date
qtdQuarter to date
ytdYear to date

Response Format​

All successful responses wrap data in a data field:

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

Paginated responses include pagination metadata:

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

Error Responses​

All errors return JSON with this structure:

{
  "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 CodeError CodeDescription
400bad_requestInvalid parameters
401unauthorizedMissing or invalid authentication
403forbiddenValid auth but insufficient permissions
404not_foundResource does not exist
409conflictResource already exists
422validation_errorSchema validation failed; error.detail lists the fields
429rate_limit_exceededToo many requests — honour Retry-After
500internal_errorServer error
503database_unavailableTemporary — honour Retry-After

Full list, including which codes are retryable: Error codes.

Documentation​

Written and maintained by the Sealmetrics Team