데이터 API
데이터 API 는 데이터 허브의 조회를 URL 하나로 제공합니다. 구글 시트 IMPORTDATA, 엑셀·Power BI 의 웹 가져오기, Python, 사내 배치가 같은 주소를 씁니다.
파라미터 이름과 필터 문법은 windsor.ai Connectors API 와 같아서, windsor 쿼리를 주소만 바꿔 옮길 수 있습니다.
1. 키 만들기
- 데이터 허브 > 데이터 API 키 로 이동합니다(조직 소유자·관리자만 발급할 수 있습니다).
- 키 이름(예:
마케팅 주간 시트)을 넣고 키 만들기를 누릅니다. - 노란 상자의 키(
adsdh_…)를 지금 복사하세요. 다시 보여주지 않습니다. 잃어버리면 폐기하고 새로 만드세요.
데이터 API 키는 앱·웹에 심는 SDK 키와 다른 키입니다. SDK 키로는 데이터를 읽을 수 없고, 데이터 API 키는 이벤트를 보낼 수 없습니다. 데이터 API 키로는 조직의 광고비·매출을 읽을 수 있으니 외부에 공유하지 마세요. 쓰지 않는 키는 폐기하면 즉시 막힙니다. 마지막 사용 시각이 목록에 표시됩니다.
키를 보내는 방법(셋 중 하나):
| 방법 | 예 | 언제 |
|---|---|---|
| 쿼리 파라미터 | ?api_key=adsdh_… | 구글 시트·엑셀처럼 헤더를 못 넣는 도구 |
| 헤더 | X-Api-Key: adsdh_… | 코드·배치 (권장 — 프록시 로그에 키가 남지 않음) |
| 헤더 | Authorization: Bearer adsdh_… | 코드·배치 |
2. 엔드포인트
기본 주소: https://api.adstage.app/datahub/v1
| 메서드·경로 | 설명 | 키 |
|---|---|---|
GET /{connector}?fields=… | 데이터 조회 | 필요 |
POST /{connector} | 같은 파라미터를 JSON 본문으로 (긴 필터용) | 필요 |
GET /all?fields=… | 모든 소스 통합 조회 | 필요 |
GET /list_connectors | 커넥터 목록(키를 주면 연결 상태 포함) | 선택 |
GET /{connector}/fields | 필드 목록 | 불필요 |
GET /{connector}/options | 연결된 계정 목록·날짜 프리셋·연산자 | 필요 |
GET /destinations | 목적지 목록과 연결 방법 | 불필요 |
3. 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
fields | ✅ | 쉼표로 구분한 필드 id. 예: date,campaign,spend,clicks. 지표가 하나 이상 있어야 합니다. 차원 최대 6개, 필드 최대 40개 |
date_preset | 기간 프리셋(아래 표). 생략하면 last_30d | |
date_from / date_to | YYYY-MM-DD. date_from 이 있으면 프리셋보다 우선합니다. date_to 를 생략하면 오늘 | |
filter | JSON 배열 필터(5장). URL 에 넣을 때는 URL 인코딩 | |
select_accounts | 쉼표로 구분한 계정 id(/{connector}/options 의 accounts). /all 에서는 google_ads__<계정id> 처럼 커넥터 접두어를 붙입니다. adstage 커넥터에는 쓸 수 없습니다(광고 계정이 없는 데이터) | |
sort | 정렬할 필드 id. 앞에 - 를 붙이면 내림차순(예: -spend). 생략하면 date 가 있을 때 날짜 오름차순, 없으면 어트리뷰션 리포트 기본 정렬 | |
_max_rows | 최대 행 수. 기본 1,000, 최대 10,000 | |
_renderer | json(기본), csv, googlesheets(= csv) | |
conversion_window_days | AdStage 전환 귀속 기간(1~30일). 생략하면 윈도 없음(대시보드 기본과 같음) |
날짜 프리셋
모든 기간은 조직 타임존 기준이며 기본은 어제까지입니다. 끝에 대문자 T 를 붙이면 오늘까지 포함합니다.
| 프리셋 | 의미 |
|---|---|
today, yesterday | 오늘, 어제 |
last_7d, last_30d, last_90d, last_Nd | 어제까지 N일 (last_7dT 는 오늘까지 7일) |
last_2w, last_Nw | 어제까지 N주(N×7일) |
last_3m, last_Nm | 어제까지 N개월 |
last_1y | 어제까지 1년 |
this_week, this_month, this_year | 이번 주(월요일)·이번 달·올해 1일부터 어제까지 (T 면 오늘까지) |
last_week, last_month, last_year | 지난주·지난달·작년 전체 |
한 번에 조회할 수 있는 기간은 최대 366일입니다.
4. 필드
필드 id 는 windsor.ai 와 같은 이름과 어트리뷰션 리포트의 원래 이름을 모두 받습니다. 전체 목록은 GET /{connector}/fields 에서 확인하세요.
타입이 TEXT·DATE 이면 차원, NUMERIC·PERCENT 이면 지표입니다.
차원
| 필드 | 설명 |
|---|---|
date | 날짜(YYYY-MM-DD) |
datasource | 행의 커넥터 id(google_ads, facebook …). 광고 채널이 아닌 유입(오가닉 등)은 adstage |
source | 정규화된 채널 코드(google.ads, meta.ads …) |
campaign, campaign_id, campaign_status | 캠페인 이름·id·상태 |
adset, adset_id | 광고 세트(메타·틱톡) / 광고 그룹(구글·네이버·카카오) |
ad_name, ad_id, ad_status, ad_type | 광고(소재) |
keyword, keyword_id, search_term, match_type | 검색 광고 키워드·검색어 |
placement | 게재면(facebook / instagram / audience_network …) |
device_os, device_type, app, country, city | 기기·앱·국가·도시(AdStage 이벤트) |
지표
| 필드 | 설명 | 출처 |
|---|---|---|
spend | 광고비(조직 기준 통화) | 매체 |
impressions | 노출 | 매체 |
clicks | 클릭(매체 보고) | 매체 |
ctr | 클릭률(%) | 매체 |
cpc | 클릭당 비용 | 매체 |
cpm | 1,000회 노출당 비용 | 매체 |
conversions, conversion_value | 매체가 보고한 전환 수·전환 가치 | 매체 |
roas, cpa | 매체 전환 기준 ROAS(%)·CPA | 매체 |
tracked_clicks | AdStage 트래킹 링크 클릭(앱+웹) | AdStage |
installs | AdStage 가 귀속한 설치 | AdStage |
cpi | 광고비 ÷ 설치 | 둘 다 |
signups, purchases | 가입·구매(앱+웹) | AdStage |
revenue | 귀속 매출(조직 기준 통화) | AdStage |
roas_adstage, cpa_adstage | AdStage 매출·전환 기준 ROAS(%)·CPA | 둘 다 |
{event}_count_{app|web|total} | 임의 이벤트 건수. 예: purchase_count_total, tutorial_complete_count_app | AdStage |
{event}_value_{app|web|total} | 금액 이벤트 합계(purchase, refund, subscribe 등) | AdStage |
adstage 커넥터에는 매체 비용 필드(spend, impressions, clicks, cpm …)가 없습니다. 광고비와 함께 보려면 all 이나 매체 커넥터를 쓰세요.
5. 필터
필터는 JSON 배열입니다. 조건 하나는 [필드, 연산자, 값] 이고, 조건 사이에 "and" / "or" 를 넣으며, 배열을 중첩해 묶습니다.
| 연산자 | 뜻 | 값 예 |
|---|---|---|
eq / neq | 같음 / 다름(문자는 대소문자 구분) | "facebook", 100 |
gt gte lt lte | 초과·이상·미만·이하 | 100000, "2026-11-01" |
contains / ncontains | 포함 / 미포함(대소문자 구분) | "Sale" |
in | 목록 중 하나 | ["google_ads","tiktok"] |
null / notnull | 값 없음 / 있음 | (값 생략) |
and가or보다 먼저 묶입니다. 의도를 분명히 하려면 배열로 묶으세요.datasource필터는 커넥터 id 로 씁니다(["datasource","in",["google_ads","facebook"]]).- 지표 비교(
spend gt 100000)나or안의 조건에 쓴 차원은fields에도 넣어야 합니다. 지표는 넣지 않아도 됩니다. - 조건은 최대 30개, 중첩은 5단계까지입니다.
6. 응답
truncated: true면_max_rows에 걸려 잘린 것입니다. 기간을 줄이거나 필터를 더하세요._renderer=csv면 첫 줄이 필드 id 인 CSV 를 돌려줍니다.
7. 오류와 한도
오류는 {"error":{"code","message","details"}} 형식입니다.
| HTTP | code | 원인 |
|---|---|---|
| 400 | invalid_request | 모르는 필드·프리셋·연산자, 366일 초과, 준비 중 커넥터 등 (message 에 고칠 방법) |
| 401 | authentication_error | 키가 없거나 틀렸거나 폐기됨 |
| 404 | not_found | 없는 커넥터 id |
| 429 | rate_limit_exceeded | 한도 초과. Retry-After 헤더의 초만큼 기다리세요 |
| 503 | server_error | 데이터 레이크가 바쁘거나 일시 장애. 1분 뒤 다시 시도 |
| 504 | server_error | 쿼리 시간 초과. 기간이나 필드를 줄여 다시 시도 |
| 한도 | 값 |
|---|---|
| 키당 | 분당 120회, 하루 10,000회 |
| 조직당 | 분당 300회, 동시 실행 4개 |
| 응답 | 최대 10,000행 |
8. 예시
curl
긴 필터는 POST
구글 시트
Python (pandas)

