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 2)ES, US
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

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​