Report API - Ad Control Help Center

Overview

The Report API lets you query performance data by campaign, product, unit, and creative, as well as backfill ad revenue data.

Prerequisites

An API key with report:read permission is required
See the Integrations guide for key generation instructions

Basic Information

Item	Value
Base URL	`https://lake.adrop.io`
Authentication	API key in `x-api-key` header
Content-Type	`application/json`
Max Query Range	30 days

Campaign Report

Query performance data with cross-tabulation by campaign, product, unit, and creative.

Request

POST /report

Request Parameters

Parameter	Type	Required	Description
`tab`	string	Yes	Primary grouping dimension (`campaign`, `product`, `unit`, `creative`)
`segment`	string	Yes	Cross-tabulation dimension. Must be a valid combination with `tab`.
`startDate`	string	Yes	Start date (YYYY-MM-DD)
`endDate`	string	Yes	End date (YYYY-MM-DD). Max 30 days from start date
`rollups`	string[]	No	Time granularity options. `date` adds daily breakdown, `time` adds hourly breakdown
`filters`	object[]	No	Filter results by specific IDs

Valid tab × segment Combinations

tab	Available segments
`campaign`	`campaign`, `unit`, `creative`
`product`	`campaign`, `product`, `unit`, `creative`
`unit`	`campaign`, `product`, `unit`, `creative`
`creative`	`unit`, `creative`

Filter Format

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

field accepts campaign, product, unit, or creative. value is an array of matching IDs. When multiple filters are set, only data matching ALL conditions is returned.

Example Request

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

Response

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

Response Fields

summary contains grand totals, items contains individual detail rows.

Common Fields

Field	Type	Description
`tab`	string	Primary dimension ID
`segment`	string	Cross-tabulation dimension ID (when tab ≠ segment)
`date_tz`	string	Date (when rollups includes `date`)
`hour_tz`	string	Hour range, e.g. “09-10” (when rollups includes `time`)
`id`	string	Entity ID
`title`	string	Entity name

Performance Metrics

Field	Type	Description
`impressions`	number	Total impressions (display + video)
`impressions_d`	number	Display impressions
`impressions_v`	number	Video impressions
`clicks`	number	Total clicks (display + video)
`clicks_d`	number	Display clicks
`clicks_v`	number	Video clicks
`dismisses`	number	Dismiss count
`ctr`	number	Click-through rate (clicks / impressions). 0.027 = 2.7%
`ctr_d`	number	Display CTR
`ctr_v`	number	Video CTR

Campaign Info (when tab or segment is campaign)

Field	Type	Description
`campaign`	string	Campaign ID
`campaign_name`	string	Campaign name
`campaign_status`	string	Campaign status
`start_time`	string	Campaign start time
`end_time`	string	Campaign end time
`target_impressions`	number	Target impressions
`target_clicks`	number	Target clicks
`advertiser_name`	string	Advertiser name
`agency_name`	string	Agency name
`agency_email`	string	Agency email

Product/Unit/Creative Info

Field	Type	Description
`product` / `product_name`	string	Product ID / name
`unit` / `unit_name`	string	Unit ID / name
`creative` / `creative_name`	string	Creative ID / name
`creative_status`	string	Creative status

Cost/Settlement Info

Field	Type	Description
`supply_amount`	number	Supply amount (budget)
`refund_amount`	number	Refund amount
`commission`	number	Commission
`settlement`	number	Final settlement (supply - commission - refund)
`payment_type`	string	Payment type (card, bank, etc.)
`pricing_type`	string	Pricing type (CPM, CPC, CPP, etc.)
`price`	number	Unit price
`cost`	number	Actual cost
`currency`	string	Currency code (USD, KRW, etc.)

Backfill Report

Query backfill ad revenue data broken down by unit and date. All monetary values are in USD.

Request

POST /report/backfill

Request Parameters

Parameter	Type	Required	Description
`startDate`	string	Yes	Start date (YYYY-MM-DD)
`endDate`	string	Yes	End date (YYYY-MM-DD). Max 30 days from start date

Example Request

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

Response

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

Response Fields

Field	Type	Description
`unit`	string	Unit ID
`unit_name`	string	Unit name
`date`	string	Date (YYYY-MM-DD)
`impressions`	number	Impression count
`showRate`	number	Show rate (impressions / fills). 0.85 = 85%
`clicks`	number	Click count
`ctr`	number	Click-through rate. 0.027 = 2.7%
`cpc`	number	Cost per click (USD)
`cpm`	number	Cost per mille (USD)
`revenue`	number	Revenue (USD)

Error Codes

HTTP Status	Description
`400`	Bad request. Date range exceeds 30 days, invalid tab × segment combination, etc.
`401`	API key is missing or invalid
`403`	Missing `report:read` permission
`502`	Internal service error. Please retry later

Limitations

Maximum query range per request is 30 days.
Date format must be YYYY-MM-DD (ISO 8601).
Per-key rate limits are not currently enforced but may be introduced in the future.

​Overview

​Prerequisites

​Basic Information

​Campaign Report

​Request

​Request Parameters

​Valid tab × segment Combinations

​Filter Format

​Example Request

​Response

​Response Fields

​Common Fields

​Performance Metrics

​Campaign Info (when tab or segment is campaign)

​Product/Unit/Creative Info

​Cost/Settlement Info

​Backfill Report

​Request

​Request Parameters

​Example Request

​Response

​Response Fields

​Error Codes

​Limitations

Overview

Prerequisites

Basic Information

Campaign Report

Request

Request Parameters

Valid tab × segment Combinations

Filter Format

Example Request

Response

Response Fields

Common Fields

Performance Metrics

Campaign Info (when tab or segment is campaign)

Product/Unit/Creative Info

Cost/Settlement Info

Backfill Report

Request

Request Parameters

Example Request

Response

Response Fields

Error Codes

Limitations