> ## 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`権限）
* 発行方法の詳細は[連携ガイド](/ja/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                                |
| `ctr_v`         | number | ビデオCTR                                   |

#### キャンペーン情報（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 | 千回インプレッション単価（USD）              |
| `revenue`     | number | 収益（USD）                        |

***

## エラーコード

| HTTPステータス | 説明                                           |
| --------- | -------------------------------------------- |
| `400`     | 不正なリクエスト。日付範囲超過（30日）、無効なtab × segment組み合わせなど |
| `401`     | APIキーがないか無効                                  |
| `403`     | `report:read`権限がない                           |
| `502`     | 内部サービスエラー。しばらくしてから再試行してください                  |

***

## 制限事項

* 1回のリクエストで照会できる最大期間は**30日**です。
* 日付形式は**YYYY-MM-DD**（ISO 8601）のみサポートします。
* APIキーごとのリクエスト制限は現在適用されていませんが、今後変更される可能性があります。