> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Report API

> Learn how to query campaign performance and backfill revenue data via API.

## 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](/integrations/overview) 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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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.