> ## 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.

# 리포트 API

> API로 캠페인 성과 및 백필 수익 데이터를 조회하는 방법을 안내합니다.

## 개요

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

### 사전 준비

* API 키 발급 필요 (`report:read` 권한)
* 자세한 발급 방법은 [연동 가이드](/ko/integrations/overview)를 참고하세요

### 기본 정보

| 항목           | 값                        |
| ------------ | ------------------------ |
| 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 형식

```json theme={null}
{
  "filters": [
    {
      "field": "campaign",
      "value": ["CAMPAIGN_ID_1", "CAMPAIGN_ID_2"]
    }
  ]
}
```

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

### 요청 예시

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

### 응답

```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
    }
  ]
}
```

### 응답 필드

`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일 |

### 요청 예시

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

### 응답

```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
    }
  ]
}
```

### 응답 필드

| 필드            | 타입     | 설명                        |
| ------------- | ------ | ------------------------- |
| `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 키당 요청 제한은 현재 적용되지 않으나, 추후 변경될 수 있습니다.