Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt

Use this file to discover all available pages before exploring further.

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://api2.upstackified.com, grouped by service path:
  • /db-mgmt/api/* — analytics queries and the measures catalog.
  • /accounts/api/* — dashboard view management.
Both surfaces share the same authentication.

​
Authentication

Every request carries two headers:
HeaderValue
x-api-keyYour Upstack API key. Starts with upstack_.
x-pixel-idThe 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://api2.upstackified.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.
ScopeGrants
analytics:readPOST /api/query, POST /api/query-attribution, POST /api/query-cohort-analysis
dashboards:readGET /api/dashboard/views (list and individual)
dashboards:writePOST / PATCH / DELETE on /api/dashboard/views, plus /copy and /from-preset. Implies dashboards:read.
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"] }
  ]
}
StatusMeaning
200Success.
400Validation error — see errors array.
401Missing/invalid x-api-key or x-pixel-id, revoked key, or expired key.
403Key is valid but doesn’t carry the required scope.
404Resource not found (or belongs to another pixel — we return 404 rather than leak existence).
500Server 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://api2.upstackified.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://api2.upstackified.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.