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
- Go to Data Hub > Data API Keys (organization OWNER / ADMIN only).
- Enter a name (e.g.
Marketing weekly sheet) and press Create key. - 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):
| Method | Example | When |
|---|---|---|
| Query parameter | ?api_key=adsdh_… | Tools that cannot set headers (Google Sheets, Excel) |
| Header | X-Api-Key: adsdh_… | Code and batch jobs (recommended — keeps the key out of proxy logs) |
| Header | Authorization: Bearer adsdh_… | Code and batch jobs |
2. Endpoints
Base URL: https://api.adstage.app/datahub/v1
| Method & path | Description | Key |
|---|---|---|
GET /{connector}?fields=… | Query data | Required |
POST /{connector} | Same parameters as a JSON body (for long filters) | Required |
GET /all?fields=… | All sources blended | Required |
GET /list_connectors | Connector list (with connection status when a key is given) | Optional |
GET /{connector}/fields | Field list | Not needed |
GET /{connector}/options | Connected accounts, date presets, operators | Required |
GET /destinations | Destinations and setup steps | Not needed |
3. Parameters
| Parameter | Required | Description |
|---|---|---|
fields | ✅ | Comma-separated field ids, e.g. date,campaign,spend,clicks. At least one metric. Up to 6 dimensions and 40 fields |
date_preset | Preset (table below). Default last_30d | |
date_from / date_to | YYYY-MM-DD. date_from takes precedence over the preset. date_to defaults to today | |
filter | JSON array filter (section 5). URL-encode it in a URL | |
select_accounts | Comma-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) | |
sort | Field id to sort by; prefix - for descending (e.g. -spend). Default: by date ascending when date is requested, otherwise the Attribution Report default | |
_max_rows | Maximum rows. Default 1,000, max 10,000 | |
_renderer | json (default), csv, googlesheets (= csv) | |
conversion_window_days | AdStage 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.
| Preset | Meaning |
|---|---|
today, yesterday | Today, yesterday |
last_7d, last_30d, last_90d, last_Nd | N days ending yesterday (last_7dT = 7 days ending today) |
last_2w, last_Nw | N weeks (N×7 days) ending yesterday |
last_3m, last_Nm | N months ending yesterday |
last_1y | One year ending yesterday |
this_week, this_month, this_year | From Monday / the 1st / Jan 1 to yesterday (T = to today) |
last_week, last_month, last_year | The 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
| Field | Description |
|---|---|
date | Date (YYYY-MM-DD) |
datasource | Connector id of the row (google_ads, facebook …). Non-ad traffic (organic etc.) is adstage |
source | Normalized channel code (google.ads, meta.ads …) |
campaign, campaign_id, campaign_status | Campaign name, id, status |
adset, adset_id | Ad set (Meta, TikTok) / ad group (Google, Naver, Kakao) |
ad_name, ad_id, ad_status, ad_type | Ad (creative) |
keyword, keyword_id, search_term, match_type | Search keywords and search terms |
placement | Placement (facebook / instagram / audience_network …) |
device_os, device_type, app, country, city | Device, app, country, city (AdStage events) |
Metrics
| Field | Description | Source |
|---|---|---|
spend | Ad spend (organization base currency) | Platform |
impressions | Impressions | Platform |
clicks | Clicks reported by the platform | Platform |
ctr | Click-through rate (%) | Platform |
cpc | Cost per click | Platform |
cpm | Cost per 1,000 impressions | Platform |
conversions, conversion_value | Platform-reported conversions and value | Platform |
roas, cpa | ROAS (%) and CPA on platform conversions | Platform |
tracked_clicks | AdStage tracking link clicks (app + web) | AdStage |
installs | Installs attributed by AdStage | AdStage |
cpi | Spend ÷ installs | Both |
signups, purchases | Sign-ups, purchases (app + web) | AdStage |
revenue | Attributed revenue (base currency) | AdStage |
roas_adstage, cpa_adstage | ROAS (%) and CPA on AdStage revenue and conversions | Both |
{event}_count_{app|web|total} | Count of any event, e.g. purchase_count_total, tutorial_complete_count_app | AdStage |
{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.
| Operator | Meaning | Example value |
|---|---|---|
eq / neq | Equals / not equals (text is case-sensitive) | "facebook", 100 |
gt gte lt lte | Greater / less than (or equal) | 100000, "2026-11-01" |
contains / ncontains | Contains / does not contain (case-sensitive) | "Sale" |
in | One of a list | ["google_ads","tiktok"] |
null / notnull | Empty / not empty | (no value) |
andbinds tighter thanor. Group with arrays to make intent explicit.- Filter
datasourceby connector id (["datasource","in",["google_ads","facebook"]]). - A dimension used in a metric comparison or inside an
orgroup must also be infields. Metrics don't need to be. - Up to 30 conditions and 5 levels of nesting.
6. Response
truncated: truemeans_max_rowscut the result. Shorten the range or add filters.- With
_renderer=csvthe response is CSV whose first line is the field ids.
7. Errors and limits
Errors look like {"error":{"code","message","details"}}.
| HTTP | code | Cause |
|---|---|---|
| 400 | invalid_request | Unknown field, preset or operator, more than 366 days, upcoming connector … (message says how to fix it) |
| 401 | authentication_error | Missing, wrong or revoked key |
| 404 | not_found | Unknown connector id |
| 429 | rate_limit_exceeded | Limit exceeded. Wait the seconds in the Retry-After header |
| 503 | server_error | The data lake is busy or temporarily unavailable. Retry in a minute |
| 504 | server_error | The query timed out. Narrow the date range or fields and retry |
| Limit | Value |
|---|---|
| Per key | 120 requests per minute, 10,000 per day |
| Per organization | 300 requests per minute, 4 running at once |
| Response | Up to 10,000 rows |
8. Examples
curl
POST for long filters
Google Sheets
Python (pandas)

