Introduction

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	Implies
`analytics:read`	Run queries and read the measure and filter catalogs
`dashboards:read`	Read dashboard views
`dashboards:write`	Create, update, copy, and delete dashboard views	`dashboards:read`
`account:read`	Read the account profile and order settings
`account:write`	Update the account profile and order settings	`account:read`
`costs:read`	Read cost settings, search products, read resolved variant costs
`costs:write`	Update cost settings, product COGS, and handling fees	`costs:read`
`events:write`	Send server-side tracking events

The catalogs (GET /api/measures, GET /api/filters) sit under analytics:read alongside the query endpoints, so a key that can’t query can’t enumerate what’s queryable either.

Older keys minted before mid-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.

Errors and rate limits

All errors are JSON responses with a message field and the appropriate status code. See Errors for the full response shape and status code reference, and Rate limiting for how request limits are enforced and how to retry safely.

Quickstart

Discover what measures are available, then build a dashboard from three of them. This needs a key with analytics:read and dashboards:write.

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).

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.

Open it in the dashboard

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

OVERVIEW

ACCOUNT

CATALOG

ANALYTICS

DASHBOARDS

COSTS

PRODUCTS

EVENTS

Base URL

Authentication

Scopes

Errors and rate limits

Quickstart

​Base URL

​Authentication

​Scopes

​Errors and rate limits

​Quickstart

Base URL

Authentication

Scopes

Errors and rate limits

Quickstart