adstage
Data Hub

Data API

The Data API exposes Data Hub queries as a single URL. Google Sheets IMPORTDATA, Excel and Power BI web imports, Python and internal batch jobs all use the same address. Parameter names and filter syntax match the windsor.ai Connectors API, so a windsor query moves over by changing the host.

1. Create a key

  1. Go to Data Hub > Data API Keys (organization OWNER / ADMIN only).
  2. Enter a name (e.g. Marketing weekly sheet) and press Create key.
  3. Copy the key (adsdh_…) now — it is not shown again. If you lose it, revoke it and create a new one.

A Data API key is different from the SDK key embedded in your app or website. The SDK key cannot read data, and a Data API key cannot send events. A Data API key can read the organization's spend and revenue, so keep it private. Revoke unused keys; revocation is immediate. The list shows when each key was last used.

Ways to send the key (any one):

MethodExampleWhen
Query parameter?api_key=adsdh_…Tools that cannot set headers (Google Sheets, Excel)
HeaderX-Api-Key: adsdh_…Code and batch jobs (recommended — keeps the key out of proxy logs)
HeaderAuthorization: Bearer adsdh_…Code and batch jobs

2. Endpoints

Base URL: https://api.adstage.app/datahub/v1

Method & pathDescriptionKey
GET /{connector}?fields=…Query dataRequired
POST /{connector}Same parameters as a JSON body (for long filters)Required
GET /all?fields=…All sources blendedRequired
GET /list_connectorsConnector list (with connection status when a key is given)Optional
GET /{connector}/fieldsField listNot needed
GET /{connector}/optionsConnected accounts, date presets, operatorsRequired
GET /destinationsDestinations and setup stepsNot needed

3. Parameters

ParameterRequiredDescription
fields✅Comma-separated field ids, e.g. date,campaign,spend,clicks. At least one metric. Up to 6 dimensions and 40 fields
date_presetPreset (table below). Default last_30d
date_from / date_toYYYY-MM-DD. date_from takes precedence over the preset. date_to defaults to today
filterJSON array filter (section 5). URL-encode it in a URL
select_accountsComma-separated account ids (from /{connector}/options → accounts). On /all, prefix with the connector: google_ads__<account id>. Not available on the adstage connector (it has no ad accounts)
sortField id to sort by; prefix - for descending (e.g. -spend). Default: by date ascending when date is requested, otherwise the Attribution Report default
_max_rowsMaximum rows. Default 1,000, max 10,000
_rendererjson (default), csv, googlesheets (= csv)
conversion_window_daysAdStage attribution window (1–30 days). Default: no window (same as the dashboard default)

Date presets

All ranges use the organization timezone and end yesterday by default. Append a capital T to include today.

PresetMeaning
today, yesterdayToday, yesterday
last_7d, last_30d, last_90d, last_NdN days ending yesterday (last_7dT = 7 days ending today)
last_2w, last_NwN weeks (N×7 days) ending yesterday
last_3m, last_NmN months ending yesterday
last_1yOne year ending yesterday
this_week, this_month, this_yearFrom Monday / the 1st / Jan 1 to yesterday (T = to today)
last_week, last_month, last_yearThe previous full week / month / year

One request can cover at most 366 days.

4. Fields

Field ids accept both windsor.ai names and the Attribution Report's own names. See GET /{connector}/fields for the full list. TEXT and DATE fields are dimensions; NUMERIC and PERCENT fields are metrics.

Dimensions

FieldDescription
dateDate (YYYY-MM-DD)
datasourceConnector id of the row (google_ads, facebook …). Non-ad traffic (organic etc.) is adstage
sourceNormalized channel code (google.ads, meta.ads …)
campaign, campaign_id, campaign_statusCampaign name, id, status
adset, adset_idAd set (Meta, TikTok) / ad group (Google, Naver, Kakao)
ad_name, ad_id, ad_status, ad_typeAd (creative)
keyword, keyword_id, search_term, match_typeSearch keywords and search terms
placementPlacement (facebook / instagram / audience_network …)
device_os, device_type, app, country, cityDevice, app, country, city (AdStage events)

Metrics

FieldDescriptionSource
spendAd spend (organization base currency)Platform
impressionsImpressionsPlatform
clicksClicks reported by the platformPlatform
ctrClick-through rate (%)Platform
cpcCost per clickPlatform
cpmCost per 1,000 impressionsPlatform
conversions, conversion_valuePlatform-reported conversions and valuePlatform
roas, cpaROAS (%) and CPA on platform conversionsPlatform
tracked_clicksAdStage tracking link clicks (app + web)AdStage
installsInstalls attributed by AdStageAdStage
cpiSpend ÷ installsBoth
signups, purchasesSign-ups, purchases (app + web)AdStage
revenueAttributed revenue (base currency)AdStage
roas_adstage, cpa_adstageROAS (%) and CPA on AdStage revenue and conversionsBoth
{event}_count_{app|web|total}Count of any event, e.g. purchase_count_total, tutorial_complete_count_appAdStage
{event}_value_{app|web|total}Sum of value events (purchase, refund, subscribe …)AdStage

The adstage connector has no platform cost fields (spend, impressions, clicks, cpm …). Use all or a platform connector to see spend.

5. Filters

A filter is a JSON array. A condition is [field, operator, value]; join conditions with "and" / "or"; nest arrays to group.

[["spend","gt",100000],"and",["campaign","contains","Brand"]]
[[["datasource","eq","facebook"],"or",["datasource","eq","tiktok"]],"and",["installs","gte",10]]
OperatorMeaningExample value
eq / neqEquals / not equals (text is case-sensitive)"facebook", 100
gt gte lt lteGreater / less than (or equal)100000, "2026-11-01"
contains / ncontainsContains / does not contain (case-sensitive)"Sale"
inOne of a list["google_ads","tiktok"]
null / notnullEmpty / not empty(no value)
  • and binds tighter than or. Group with arrays to make intent explicit.
  • Filter datasource by connector id (["datasource","in",["google_ads","facebook"]]).
  • A dimension used in a metric comparison or inside an or group must also be in fields. Metrics don't need to be.
  • Up to 30 conditions and 5 levels of nesting.

6. Response

{
  "data": [
    { "date": "2026-11-13", "datasource": "google_ads", "spend": 152000, "clicks": 410, "installs": 37 }
  ],
  "meta": {
    "connector": "all",
    "date_from": "2026-11-07", "date_to": "2026-11-13",
    "timezone": "Asia/Seoul", "currency": "KRW",
    "fields": [{ "id": "date", "name": "Date", "type": "DATE" }],
    "row_count": 1, "truncated": false,
    "totals": { "spend": 152000, "clicks": 410, "installs": 37 },
    "notes": ["Money fields are in KRW. …"]
  }
}
  • truncated: true means _max_rows cut the result. Shorten the range or add filters.
  • With _renderer=csv the response is CSV whose first line is the field ids.

7. Errors and limits

Errors look like {"error":{"code","message","details"}}.

HTTPcodeCause
400invalid_requestUnknown field, preset or operator, more than 366 days, upcoming connector … (message says how to fix it)
401authentication_errorMissing, wrong or revoked key
404not_foundUnknown connector id
429rate_limit_exceededLimit exceeded. Wait the seconds in the Retry-After header
503server_errorThe data lake is busy or temporarily unavailable. Retry in a minute
504server_errorThe query timed out. Narrow the date range or fields and retry
LimitValue
Per key120 requests per minute, 10,000 per day
Per organization300 requests per minute, 4 running at once
ResponseUp to 10,000 rows

8. Examples

curl

curl -H "X-Api-Key: $ADSTAGE_DATA_KEY" \
  "https://api.adstage.app/datahub/v1/facebook?fields=date,campaign,adset,spend,clicks,cpm,purchases&date_preset=last_7d"

POST for long filters

curl -X POST -H "X-Api-Key: $ADSTAGE_DATA_KEY" -H "Content-Type: application/json" \
  https://api.adstage.app/datahub/v1/all \
  -d '{"fields":["date","datasource","spend","installs","revenue"],"date_preset":"last_30d","filter":[["datasource","in",["google_ads","facebook","tiktok"]]]}'

Google Sheets

=IMPORTDATA("https://api.adstage.app/datahub/v1/all?api_key=adsdh_…&fields=date,datasource,spend,clicks,installs,revenue&date_preset=last_30d&_renderer=csv")

Python (pandas)

import os, requests, pandas as pd
 
r = requests.get(
    "https://api.adstage.app/datahub/v1/all",
    headers={"X-Api-Key": os.environ["ADSTAGE_DATA_KEY"]},
    params={"fields": "date,datasource,spend,installs,revenue", "date_preset": "last_90d"},
    timeout=120,
)
r.raise_for_status()
df = pd.DataFrame(r.json()["data"])

Table of Contents