API Overview

Programmatic access to your Upstack Data pixel — authentication, base URLs, scopes, error format, and a curl quickstart.

The Upstack Data API lets you query your event data, list the measures catalog, and manage dashboard views from anything that speaks HTTP. The same endpoints power the in-app dashboard and the upstack CLI.

If you’re scripting against Upstack from a terminal, prefer the upstack CLI — it wraps these endpoints, handles auth, and adds ergonomics like measure-title resolution.

Base URL

All endpoints in this reference are relative to https://api.upstackdata.com, grouped by service path:

• /db-mgmt/api/* — analytics queries and the measures catalog.
• /accounts/api/* — dashboard view management.
• /tr/api/* — server-side event ingestion.

These surfaces share the same authentication.

Authentication

Every request carries two headers:

Header	Value
x-api-key	Your Upstack API key. Starts with upstack_.
x-pixel-id	The pixel id this request targets. One key is scoped to one pixel.

Mint an API key in the dashboard under Settings → API Keys. The raw key is shown once at creation — store it securely; we keep only a hash.

curl https://api.upstackdata.com/db-mgmt/api/measures \
  -H "x-api-key: upstack_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "x-pixel-id: 5f1e6a4f-..."

Scopes

API keys carry one or more scopes. The required scope per endpoint is listed on each endpoint’s page.

Scope	Grants
analytics:read	POST /api/query, POST /api/query-attribution, POST /api/query-cohort-analysis
dashboards:read	GET /api/dashboard/views (list and individual)
dashboards:write	POST / PATCH / DELETE on /api/dashboard/views, plus /copy and /from-preset. Implies dashboards:read.
events:write	POST /tr/api/events — send server-side tracking events.

The catalog endpoint (GET /api/measures) is ungated — any active key can read the measures list. This unblocks discovery use cases (e.g. an LLM looking up canonical measure ids before composing a query).

Older keys minted before May 2026 may carry legacy scopes db_query or attribution_query. These are auto-expanded to analytics:read at request time, so existing keys keep working without rotation. Rotate at your convenience to switch to the modern names.

Error format

Errors are JSON responses with a message field and the appropriate status code.

{
  "message": "API key does not have the dashboards:write scope"
}

400 responses on validated endpoints also include an errors array with per-field detail:

{
  "message": "Bad Request",
  "errors": [
    { "message": "name is required", "key": "name", "path": ["name"] }
  ]
}

The server-side events API (POST /tr/api/events) returns a richer envelope: the same top-level message, plus a requestId and a structured error object with a machine-readable code and per-event details. See Send server-side events for the full shape.

Status	Meaning
200	Success.
400	Validation error — see errors (or error.details on the events API).
401	Missing/invalid x-api-key or x-pixel-id, revoked key, or expired key.
403	Key is valid but doesn’t carry the required scope.
404	Resource not found (or belongs to another pixel — we return 404 rather than leak existence).
413	Request body too large (server-side events API — 128 KB limit).
500	Server error. Retry; if persistent, file a support ticket with the request id.

Quickstart

Discover what measures are available, then build a dashboard from three of them.

1. List measures

   curl https://api.upstackdata.com/db-mgmt/api/measures \
     -H "x-api-key: $UPSTACK_API_KEY" \
     -H "x-pixel-id: $UPSTACK_PIXEL_ID"
   

   Find the keys you want (e.g. core.new_customer_roas, core.new_customer_mer, meta.cpm).

2. Build a dashboard from those measures

   curl -X POST https://api.upstackdata.com/accounts/api/dashboard/views/from-preset \
     -H "x-api-key: $UPSTACK_API_KEY" \
     -H "x-pixel-id: $UPSTACK_PIXEL_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "NC + Meta Pulse",
       "widgets": [
         { "measure": "core.new_customer_roas", "title": "NC ROAS" },
         { "measure": "core.new_customer_mer", "title": "NC MER" },
         { "measure": "meta.cpm", "title": "Meta CPM" }
       ]
     }'
   

   The response returns the full DashboardView with auto-laid-out sparkline widgets.

3. Open it in the dashboard

   Sign in to app.upstackdata.com and pick the new view from the view dropdown.

For the same flow as a single CLI command, see upstack dashboard view build.