리포트 API - Ad Control Help Center

개요

리포트 API를 사용하면 캠페인, 상품, 유닛, 소재별 성과 데이터와 백필 광고 수익 데이터를 조회할 수 있습니다.

사전 준비

API 키 발급 필요 (report:read 권한)
자세한 발급 방법은 연동 가이드를 참고하세요

기본 정보

항목	값
Base URL	`https://lake.adrop.io`
인증	`x-api-key` 헤더에 API 키 포함
Content-Type	`application/json`
최대 조회 기간	30일

캠페인 리포트

캠페인, 상품, 유닛, 소재별 성과 데이터를 교차 분석하여 조회합니다.

요청

POST /report

요청 파라미터

파라미터	타입	필수	설명
`tab`	string	O	기본 그룹핑 차원 (`campaign`, `product`, `unit`, `creative`)
`segment`	string	O	교차 분석 차원. `tab`과의 유효 조합을 확인하세요.
`startDate`	string	O	시작일 (YYYY-MM-DD)
`endDate`	string	O	종료일 (YYYY-MM-DD). 시작일로부터 최대 30일
`rollups`	string[]	-	시간 세분화 옵션. `date`는 일별, `time`은 시간대별 데이터 추가
`filters`	object[]	-	특정 ID로 결과를 필터링

tab × segment 유효 조합

tab	사용 가능한 segment
`campaign`	`campaign`, `unit`, `creative`
`product`	`campaign`, `product`, `unit`, `creative`
`unit`	`campaign`, `product`, `unit`, `creative`
`creative`	`unit`, `creative`

filters 형식

{
  "filters": [
    {
      "field": "campaign",
      "value": ["CAMPAIGN_ID_1", "CAMPAIGN_ID_2"]
    }
  ]
}

field에는 campaign, product, unit, creative 중 하나를 지정하고, value에 해당 ID 배열을 전달합니다. 여러 필터를 설정하면 모든 조건을 만족하는 데이터만 반환됩니다.

요청 예시

curl -X POST https://lake.adrop.io/report \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tab": "campaign",
    "segment": "unit",
    "startDate": "2026-03-01",
    "endDate": "2026-03-07",
    "rollups": ["date"]
  }'

응답

{
  "summary": {
    "impressions": 125000,
    "impressions_d": 100000,
    "impressions_v": 25000,
    "clicks": 3750,
    "clicks_d": 3000,
    "clicks_v": 750,
    "dismisses": 200,
    "ctr": 0.03,
    "ctr_d": 0.03,
    "ctr_v": 0.03
  },
  "items": [
    {
      "tab": "01J...",
      "segment": "01J...",
      "date_tz": "2026.03.01.",
      "id": "01J...",
      "title": "Campaign A",
      "campaign": "01J...",
      "campaign_name": "Campaign A",
      "campaign_status": "active",
      "unit": "01J...",
      "unit_name": "Banner Top",
      "impressions": 5000,
      "impressions_d": 4000,
      "impressions_v": 1000,
      "clicks": 150,
      "clicks_d": 120,
      "clicks_v": 30,
      "dismisses": 10,
      "ctr": 0.03,
      "ctr_d": 0.03,
      "ctr_v": 0.03
    }
  ]
}

응답 필드

summary는 전체 합계, items는 개별 상세 데이터입니다.

공통 필드

필드	타입	설명
`tab`	string	기본 차원 ID
`segment`	string	교차 차원 ID (tab ≠ segment일 때)
`date_tz`	string	날짜 (rollups에 `date` 포함 시)
`hour_tz`	string	시간대, 예: “09-10” (rollups에 `time` 포함 시)
`id`	string	엔티티 ID
`title`	string	엔티티 이름

성과 지표

필드	타입	설명
`impressions`	number	총 노출수 (디스플레이 + 비디오)
`impressions_d`	number	디스플레이 노출수
`impressions_v`	number	비디오 노출수
`clicks`	number	총 클릭수 (디스플레이 + 비디오)
`clicks_d`	number	디스플레이 클릭수
`clicks_v`	number	비디오 클릭수
`dismisses`	number	닫기 수
`ctr`	number	클릭률 (clicks / impressions). 0.027 = 2.7%
`ctr_d`	number	디스플레이 클릭률
`ctr_v`	number	비디오 클릭률

캠페인 정보 (tab 또는 segment가 campaign일 때)

필드	타입	설명
`campaign`	string	캠페인 ID
`campaign_name`	string	캠페인 이름
`campaign_status`	string	캠페인 상태
`start_time`	string	캠페인 시작일
`end_time`	string	캠페인 종료일
`target_impressions`	number	목표 노출수
`target_clicks`	number	목표 클릭수
`advertiser_name`	string	광고주 이름
`agency_name`	string	대행사 이름
`agency_email`	string	대행사 이메일

상품/유닛/소재 정보

필드	타입	설명
`product` / `product_name`	string	상품 ID / 이름
`unit` / `unit_name`	string	유닛 ID / 이름
`creative` / `creative_name`	string	소재 ID / 이름
`creative_status`	string	소재 상태

비용/정산 정보

필드	타입	설명
`supply_amount`	number	공급가 (예산)
`refund_amount`	number	환불 금액
`commission`	number	수수료
`settlement`	number	최종 정산 금액 (공급가 - 수수료 - 환불)
`payment_type`	string	결제 유형 (card, bank 등)
`pricing_type`	string	과금 유형 (CPM, CPC, CPP 등)
`price`	number	단가
`cost`	number	실제 비용
`currency`	string	통화 코드 (USD, KRW 등)

백필 리포트

백필 광고 수익 데이터를 유닛별, 일별로 조회합니다. 모든 금액은 USD 기준입니다.

요청

POST /report/backfill

요청 파라미터

파라미터	타입	필수	설명
`startDate`	string	O	시작일 (YYYY-MM-DD)
`endDate`	string	O	종료일 (YYYY-MM-DD). 시작일로부터 최대 30일

요청 예시

curl -X POST https://lake.adrop.io/report/backfill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-03-01",
    "endDate": "2026-03-07"
  }'

응답

{
  "summary": {
    "impressions": 50000,
    "clicks": 1500,
    "ctr": 0.03,
    "cpc": 0.12,
    "cpm": 2.5,
    "revenue": 125.0,
    "showRate": 0.85
  },
  "items": [
    {
      "unit": "01J...",
      "unit_name": "Banner Top",
      "date": "2026-03-01",
      "impressions": 8000,
      "showRate": 0.85,
      "clicks": 240,
      "ctr": 0.03,
      "cpc": 0.12,
      "cpm": 2.5,
      "revenue": 20.0
    }
  ]
}

응답 필드

필드	타입	설명
`unit`	string	유닛 ID
`unit_name`	string	유닛 이름
`date`	string	날짜 (YYYY-MM-DD)
`impressions`	number	노출수
`showRate`	number	노출률 (노출 / 채움). 0.85 = 85%
`clicks`	number	클릭수
`ctr`	number	클릭률. 0.027 = 2.7%
`cpc`	number	클릭당 비용 (USD)
`cpm`	number	1,000회 노출당 비용 (USD)
`revenue`	number	수익 (USD)

에러 코드

HTTP 상태	설명
`400`	잘못된 요청. 날짜 범위 초과(30일), 잘못된 tab × segment 조합 등
`401`	API 키가 없거나 유효하지 않음
`403`	`report:read` 권한이 없음
`502`	내부 서비스 오류. 잠시 후 다시 시도하세요

제한사항

한 번에 조회할 수 있는 최대 기간은 30일입니다.
날짜 형식은 YYYY-MM-DD (ISO 8601)만 지원합니다.
API 키당 요청 제한은 현재 적용되지 않으나, 추후 변경될 수 있습니다.

​개요

​사전 준비

​기본 정보

​캠페인 리포트

​요청

​요청 파라미터

​tab × segment 유효 조합

​filters 형식

​요청 예시

​응답

​응답 필드

​공통 필드

​성과 지표

​캠페인 정보 (tab 또는 segment가 campaign일 때)

​상품/유닛/소재 정보

​비용/정산 정보

​백필 리포트

​요청

​요청 파라미터

​요청 예시

​응답

​응답 필드

​에러 코드

​제한사항

개요

사전 준비

기본 정보

캠페인 리포트

요청

요청 파라미터

tab × segment 유효 조합

filters 형식

요청 예시

응답

응답 필드

공통 필드

성과 지표

캠페인 정보 (tab 또는 segment가 campaign일 때)

상품/유닛/소재 정보

비용/정산 정보

백필 리포트

요청

요청 파라미터

요청 예시

응답

응답 필드

에러 코드

제한사항