Analytics and management API

Use this API from your server, the CLI, MCP or Raycast. Choose a website key under Settings → API access, or a workspace key under Account → Agent access. Workspace keys cover websites you own, including future ones; shared team websites and the demo are excluded. Raw visitor records, billing and imports are outside this API.

Analytics requests use the same current calculation engine as the dashboard. Prepared results retain their captured values until normal cache expiry; request a new analysis to include later records.

Create a key

1. Open website Settings → API access, or Account → Agent access for workspace access.
2. Enter a recognizable Key name, select only the needed permissions and choose Create analytics key.
3. Copy the new secret and save it as SEEAN_ANALYTICS_KEY in your server or local tool environment. It is shown only when created; leaving the page or dismissing it removes that view.
4. Copy API endpoint into SEEAN_ANALYTICS_ENDPOINT in that environment.

Each website supports up to 10 active keys, plus up to 10 workspace keys per owner. Demo websites cannot create them. If clipboard access fails, select and copy the secret field manually. A refused request shows the server’s reason; a rate-limited one says how many seconds to wait. Use separate names for separate tools so you can identify which key to revoke.

While a website is open, Find → API access also opens this settings tab.

Keep keys out of browser code, public repositories, URLs and prompts sent to unrelated services. Tracker tokens, shared-dashboard URLs and revenue write keys cannot authenticate this API.

Make a request

Send a JSON POST with a Bearer key:

curl --fail-with-body "$SEEAN_ANALYTICS_ENDPOINT" \
  --header "Authorization: Bearer $SEEAN_ANALYTICS_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operation":"list_sites"}'

list_sites returns authorized owned websites with id, name and domain. It does not return account details. Website keys infer their own site; workspace keys require siteId for individual-site operations. Another owner’s ID is refused. On list_sites and get_live, an optional siteId asserts access and does not narrow the list.

Permissions

New keys default to the two read permissions. Existing legacy keys keep their original six traffic operations; they gain neither management, revenue nor tracking-token access. Create a scoped replacement if needed. Permissions are fixed when a key is created; replace and revoke to change them.

Read operations

Overview series contain t (Unix milliseconds), visitors, views, visits, bounceRate (0-1) and sessionTime (milliseconds). Previous-period series use the same fields. Visit buckets and weighted averages follow the KPI chart definitions. Older completed job IDs can lack the last three fields; start a new request without jobId to calculate them.

Traffic results omit revenue and order counts even if a key has revenue permission. Only get_revenue returns financial aggregates. No operation returns raw activity or visitor/session identifiers. Setup health proves recent receipt, not that every route or payment integration works. Traffic uses the dashboard’s metric definitions.

Dates, filters and comparisons

Overview, pages, sources, next actions and revenue accept range, defaulting to 30d. Presets are 30m, 12h, 24h, 7d, 30d, 60d, 90d, 12mo and all; all is bounded to the latest 1,098 days. Presets end at the start of the current minute, so repeated requests share a period.

For exact reconciliation, send custom:FROM:TO with Unix timestamps in milliseconds. FROM is included and TO excluded; the interval must be positive and at most 1,098 days. Match the returned from and to in the dashboard. API series buckets are UTC calendar days (or UTC-aligned hours for short ranges); the dashboard buckets the same period in the account’s display time zone, so per-day rows can differ while totals agree. Realtime and setup health always use thirty minutes and reject custom ranges, filters and comparisons.

An optional filter accepts path, entry, exit, ref, country, browser, os, device, event, conversion, utmSource, utmMedium, utmCampaign, utmTerm and utmContent, each a string of at most 300 characters. Most filters select matching sessions. conversion first selects visitors who triggered the exact event name in the period, including their other visits; remaining filters then narrow matching sessions. Comparisons qualify visitors independently in each interval. Revenue rejects session filters. Example:

{
  "operation": "get_overview",
  "range": "7d",
  "filter": { "country": "US", "path": "/pricing" },
  "compare": "previous"
}

compare accepts none or previous. Previous-period KPIs and series appear in Overview; pages and sources return current-period breakdowns. Queries and hash fragments are not separate tracked paths.

Management operations

• create_site: requires name and domain, a workspace key and sites:write. The account limit is 30 websites.
• update_site: requires siteId for workspace keys and at least one of name or domain. Changing the domain disconnects its Search Console integration, as in the website settings.
• rotate_site_token: replaces and returns the public tracking token. Update all installed snippets; old tokens stop collecting.
• delete_site: requires confirmation: "DELETE example.com" using the website’s exact current domain. Deletes the website and schedules its associated data cleanup.
• reset_site_stats: requires confirmation: "RESET example.com". Removes statistics while preserving site settings, token, integrations and usage accounting. The same preservation and active-import checks as Danger zone apply.

Writes return status: "ready" when accepted. They do not accept analysis options. A missing or incorrect destructive phrase returns 400 with the required phrase and makes no change. Never have an agent invent confirmation on behalf of a user. If a write times out, check the website before retrying: the server may have completed it.

Wait for a report

HTTP 202 with status: "pending", jobId, site and period means preparation is running. Respect Retry-After and poll the same operation with the returned ID:

{ "operation": "get_overview", "jobId": "RETURNED_JOB_ID" }

Do not include range, filter or compare while polling. HTTP 200 with status: "ready" includes data, computedAt, from, to, filter and comparison. Ready empty data means no matching recorded traffic. HTTP 200 with status: "failed" contains an error and no data; start a new analysis or contact support. Job IDs are temporary references, not permanent reports or credentials.

Check both HTTP and JSON status. Scope is checked again when polling; revoked keys cannot fetch earlier requests. To refresh a completed report, start another request without jobId; a recent matching result may be reused.

Limits and errors

The body is limited to 4 KiB. Unknown fields and invalid option combinations are rejected. Limits allow 60 calls per minute per key with a burst of 20, and 120 per minute across the owner account with a burst of 40. Polls count. Existing account analysis-capacity limits also apply.

Browser cross-origin access and remote MCP hosting are not provided. Creating a key does not install a local client. Use the CLI, local MCP adapter or Raycast Script Command.

Revoke or replace a key

Under Active keys, choose Revoke and confirm Revoke key. Future requests, including polling, lose access immediately. Keys have no automatic expiry. Deleting the website or account also removes access.

To replace a key, create a new one, update your tool, verify a request, then revoke the old key. Revoking the old key keeps the new key’s secret on screen; only revoking the key the shown secret belongs to hides it. Revocation cannot erase already downloaded results. For a person’s browser view, use shared dashboards.

Unfiltered Overview reads include accepted complete imported days. Daily visitors are summed using source definitions; KPIs missing from any imported day are null, with imported.days and imported.missing metadata. Missing bucket metrics are omitted. Session filters exclude history. These keys cannot upload or remove imports.

Something unclear? Contact support.