adstage
데이터 허브

데이터 API

데이터 API 는 데이터 허브의 조회를 URL 하나로 제공합니다. 구글 시트 IMPORTDATA, 엑셀·Power BI 의 웹 가져오기, Python, 사내 배치가 같은 주소를 씁니다. 파라미터 이름과 필터 문법은 windsor.ai Connectors API 와 같아서, windsor 쿼리를 주소만 바꿔 옮길 수 있습니다.

1. 키 만들기

  1. 데이터 허브 > 데이터 API 키 로 이동합니다(조직 소유자·관리자만 발급할 수 있습니다).
  2. 키 이름(예: 마케팅 주간 시트)을 넣고 키 만들기를 누릅니다.
  3. 노란 상자의 키(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_toYYYY-MM-DD. date_from 이 있으면 프리셋보다 우선합니다. date_to 를 생략하면 오늘
filterJSON 배열 필터(5장). URL 에 넣을 때는 URL 인코딩
select_accounts쉼표로 구분한 계정 id(/{connector}/options 의 accounts). /all 에서는 google_ads__<계정id> 처럼 커넥터 접두어를 붙입니다. adstage 커넥터에는 쓸 수 없습니다(광고 계정이 없는 데이터)
sort정렬할 필드 id. 앞에 - 를 붙이면 내림차순(예: -spend). 생략하면 date 가 있을 때 날짜 오름차순, 없으면 어트리뷰션 리포트 기본 정렬
_max_rows최대 행 수. 기본 1,000, 최대 10,000
_rendererjson(기본), csv, googlesheets(= csv)
conversion_window_daysAdStage 전환 귀속 기간(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클릭당 비용매체
cpm1,000회 노출당 비용매체
conversions, conversion_value매체가 보고한 전환 수·전환 가치매체
roas, cpa매체 전환 기준 ROAS(%)·CPA매체
tracked_clicksAdStage 트래킹 링크 클릭(앱+웹)AdStage
installsAdStage 가 귀속한 설치AdStage
cpi광고비 ÷ 설치둘 다
signups, purchases가입·구매(앱+웹)AdStage
revenue귀속 매출(조직 기준 통화)AdStage
roas_adstage, cpa_adstageAdStage 매출·전환 기준 ROAS(%)·CPA둘 다
{event}_count_{app|web|total}임의 이벤트 건수. 예: purchase_count_total, tutorial_complete_count_appAdStage
{event}_value_{app|web|total}금액 이벤트 합계(purchase, refund, subscribe 등)AdStage

adstage 커넥터에는 매체 비용 필드(spend, impressions, clicks, cpm …)가 없습니다. 광고비와 함께 보려면 all 이나 매체 커넥터를 쓰세요.

5. 필터

필터는 JSON 배열입니다. 조건 하나는 [필드, 연산자, 값] 이고, 조건 사이에 "and" / "or" 를 넣으며, 배열을 중첩해 묶습니다.

[["spend","gt",100000],"and",["campaign","contains","brand"]]
[[["datasource","eq","facebook"],"or",["datasource","eq","tiktok"]],"and",["installs","gte",10]]
연산자뜻값 예
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. 응답

{
  "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 면 _max_rows 에 걸려 잘린 것입니다. 기간을 줄이거나 필터를 더하세요.
  • _renderer=csv 면 첫 줄이 필드 id 인 CSV 를 돌려줍니다.

7. 오류와 한도

오류는 {"error":{"code","message","details"}} 형식입니다.

HTTPcode원인
400invalid_request모르는 필드·프리셋·연산자, 366일 초과, 준비 중 커넥터 등 (message 에 고칠 방법)
401authentication_error키가 없거나 틀렸거나 폐기됨
404not_found없는 커넥터 id
429rate_limit_exceeded한도 초과. Retry-After 헤더의 초만큼 기다리세요
503server_error데이터 레이크가 바쁘거나 일시 장애. 1분 뒤 다시 시도
504server_error쿼리 시간 초과. 기간이나 필드를 줄여 다시 시도
한도값
키당분당 120회, 하루 10,000회
조직당분당 300회, 동시 실행 4개
응답최대 10,000행

8. 예시

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

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"]]]}'

구글 시트

=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"])

목차