# API リファレンス：レポート

> https://okaeri.tech/developers/reference/reports/ の Markdown 版。

レポート（`reports`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/reports/funnel](https://okaeri.tech/developers/reference/reports.md#getFunnelReport)　ファネルと指標のレポート（`getFunnelReport`）
- [GET /api/v1/reports/daily](https://okaeri.tech/developers/reference/reports.md#getDailyReport)　日次推移のレポート（`getDailyReport`）

## GET /api/v1/reports/funnel

**ファネルと指標のレポート**

operationId：`getFunnelReport`　必要なスコープ：`reports:read`

期間は**半開区間 [from, to)**。日時はオフセット付き ISO 8601 のみ受け付ける。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `from` | クエリ | `string` | 必須 | — |
| `to` | クエリ | `string` | 必須 | — |
| `site_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `campaign_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `group_by` | クエリ | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [FunnelReportOut](https://okaeri.tech/developers/reference/schemas.md#FunnelReportOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## GET /api/v1/reports/daily

**日次推移のレポート**

operationId：`getDailyReport`　必要なスコープ：`reports:read`

期間は **JST の日付の半開区間 [from, to)**（`YYYY-MM-DD`）。

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `from` | クエリ | `string` | 必須 | — |
| `to` | クエリ | `string` | 必須 | — |
| `site_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `campaign_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `scenario_id` | クエリ | `string`（uuid）（null 可） | — | — |
| `group_by` | クエリ | `string`（null 可） | — | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 200 | 成功 | [DailyReportOut](https://okaeri.tech/developers/reference/schemas.md#DailyReportOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |