# 分析およびレポート API

これらの読み取り専用エンドポイントを使用すると、メッセージイベント数、クレジット消費量、AI利用料金、アプリ内ダッシュボードに表示されるものと同じチャートやインサイトなど、アカウントのアクティビティを独自のダッシュボードやレポートに取り込むことができます。このガイドでは以下について説明します。

- **サマリー** — メッセージボリュームのカウンター（送信、配信、開封、返信、予約、作成された連絡先、クレジット）。
- **クレジット** — 合計と内訳を含む、クレジット使用状況の詳細なページ分割された台帳。
- **AIコスト** — AI利用料金の日次ロールアップ。
- **メトリクスシリーズ** — キャンペーン、チャネル、AIエージェント、または番号ごとにグループ化された、1つ以上のメトリクスのチャート対応時系列データ。
- **会話の成果** — AIが割り当てた成果タグごとの会話の終了状況。
- **ダッシュボードインサイト** および **ダッシュボードAIインサイト** — AIが作成した要約を含む、アプリ内ダッシュボードの背後にあるすべてのデータ。
- **エンティティアクティビティ** — 個々の連絡先、案件、またはタスクのタイムライン。
- **集計イベント数** — 既存の統合のために保持されている、サマリーのレガシーなcamelCase形式。

このページのすべてのエンドポイントには、両方ではなく、正確なスコープが必要です。エンドポイントが受け入れる場合、`campaign_id`（レガシー）または`agent_id`のいずれか最大1つを渡してください。両方を送信すると`400`が返され、アカウントに存在しないIDを送信すると`403`ではなく`404`が返されるため、他のアカウントのIDは推測できないようになっています。

以下のすべてのパスは、APIベースURLからの相対パスです。

```
https://api.youraiconnector.com/v1
```

すべてのリクエストは認証されている必要があります。受け入れられる4つの認証方法については、[Authentication](authentication.md)を参照してください。ここでの例では `X-API-Key` ヘッダー（およびcURL用のクエリパラメータ形式）を使用しています。

---

## 日付範囲

3つのエンドポイントすべてで、同じオプションの日付フィルターを使用できます。

| パラメータ | 説明 |
|---|---|
| `from` | 範囲の開始日。`YYYY-MM-DD`、指定日を含みます。デフォルトは30日前です。 |
| `to` | 範囲の終了日。`YYYY-MM-DD`、指定日を含みます。デフォルトは今日です。 |

日付はUTCで解釈されます。範囲のデフォルトは**過去30日間**で、上限は**366日間**です。これより広い範囲を指定すると `400` が返されます。`from` は `to` より後の日付であってはなりません。

### `truncated` フラグ

**サマリー**および**クレジット**エンドポイントでは、1回のリクエストでスキャンできるレコード数に上限があります。指定した期間のデータ量が非常に多く、その上限に達した場合、レスポンスに `"truncated": true` が含まれます。このフラグが表示された場合、数値は部分的なスキャンに基づいています。完全な数値を取得するには、日付範囲を狭めるか（またはより短い期間でページングして）ください。

::: note
**注:** コストとトークンの数値は、お客様自身のプロバイダーAPIキーに請求されるAI呼び出しに対してのみ含まれます。お客様のアカウントでコストの数値が非表示になっている場合、レスポンスは `"costs_redacted": true` に設定され、コストフィールドはゼロとして返されます。
:::


---

## メッセージボリュームのサマリー

アカウントの集計されたメッセージイベントカウンターを、期間合計および日次シリーズの両方で返します。期間内のすべての日付が `by_date` に表示され、アクティビティのない日はゼロで埋められます。オプションで `campaign_id` を使用して、単一のキャンペーンにフィルタリングすることも可能です。

`GET /analytics/summary`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `from` | いいえ | 範囲の開始、`YYYY-MM-DD`。 |
| `to` | いいえ | 範囲の終了、`YYYY-MM-DD`。 |
| `campaign_id` | いいえ | このキャンペーンに属するイベントのみをカウントします。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}
```

`by_date` の各エントリには、`totals` と同じカウンターフィールドに加え、`date` が含まれます。

アカウントに属さない `campaign_id` を渡した場合、レスポンスは `{ "success": false, "error": "Campaign not found" }` を伴う `404` となります。

---

## クレジット使用量

指定範囲内のクレジット使用量を返します。個別のレコードのページネーションリストに加え、範囲の合計、理由別およびキャンペーン別の内訳が含まれます。

`GET /analytics/credits`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `from` | いいえ | 範囲の開始、`YYYY-MM-DD`。 |
| `to` | いいえ | 範囲の終了、`YYYY-MM-DD`。 |
| `campaign_id` | いいえ | このキャンペーンに起因する使用量のみを含めます。 |
| `limit` | いいえ | `records` のページサイズ（1～100）。デフォルトは 50 です。 |
| `cursor` | いいえ | 次のページを取得するには、前のページの `next_cursor` を渡します。 |

> **調整と消費の違い:** ボーナス、プラン更新、修正などの残高変更は、`totals` および内訳から**除外**されます。これらは実際の消費ではないためです。これらは引き続き `records` リストに表示され、`"is_adjustment": true` のフラグが付けられます。

**合計と内訳は最初のページにのみ表示されます**（`cursor` が指定されていない場合）。以降のページでは、`totals`、`by_reason`、`by_reason_cost`、および `by_campaign` は `null` として返され、`records` 配列のみが継続されます。これにより、ページごとに範囲全体を再スキャンすることを回避しています。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.
```

**レスポンス**（最初のページ）

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}
```

**フィールドに関する注記:**

- `amount` — レコードに対して請求されたクレジット。独自のプロバイダーAPIキーに請求されたレコードの場合はゼロになります。
- `is_adjustment` — 残高変更の場合は `true`（合計/内訳からは除外されます）。
- `cost_usd`、`input_tokens`、`output_tokens`、`cache_read_tokens`、`cache_creation_tokens`、`ai_model`、`request_id` — 独自のプロバイダーAPIキーに請求されたレコードにのみ入力されます。それ以外の場合はゼロまたは `null` です。
- `is_test` — プレイグラウンド/テスト実行の場合は `true`。これらは請求対象外です。
- `next_cursor` — 次のページのカーソル。レコードがこれ以上ない場合は `null` となります。

---

## AIコストのロールアップ

アカウントの1日あたりのAI利用料金のロールアップを返します。これは事前に集計された日次合計を読み取るため、長い期間であっても高速です。範囲内のすべての日が `days` に表示され、利用のない日はゼロで埋められます。

`GET /analytics/ai-cost`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `from` | いいえ | 範囲の開始、`YYYY-MM-DD`。 |
| `to` | いいえ | 範囲の終了、`YYYY-MM-DD`。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}
```

**フィールドに関する注記:**

- `byok_usd` — 独自のプロバイダーAPIキーに請求される利用料金。
- `platform_usd` — 独自のキーではなく、プラットフォーム上で実行された利用料金の割合。
- `input_usd`、`output_usd`、`cache_creation_usd`、`cache_read_usd` — `total_usd`を構成するコスト要素。
- `by_provider` — AIプロバイダー名ごとの米ドルでの利用料金。
- 米ドルでの数値は、独自のプロバイダーキーを使用しているアカウントにのみ返されます。クレジット支払いのアカウントの場合、すべての米ドルフィールドはゼロになり、`costs_redacted`は`true`になります（呼び出し回数は引き続き表示されます）。

---

## メトリクスシリーズ

1回の呼び出しで1つ以上のメトリクス時系列を返します。オプションで最大2つのディメンションでグループ化でき、チャートをバインドするためのエンドポイントです。1回の要求で「このキャンペーンのチャネルごとの1日あたりの送信数と返信数」といった回答が得られるため、キャンペーンごとに呼び出す必要はありません。

`GET /analytics/series`

すべてのレスポンスには`labels`配列（全範囲にわたってゼロ埋めされた時間軸）と、グループごとに`series`のエントリが含まれます。各エントリには、要求されたメトリクスごとに`labels`に合わせた配列が保持されます。`limit`より前のシリーズは削除されず、`other_bucket`に集約されます。これは範囲合計から返されたシリーズを差し引いて計算されるため、レンダリングされたチャートは常に実際の数値と一致します。これが発生すると、`truncated`は`true`になります。

数値の算出元：`sent`、`delivered`、`read`、および`replied`は、チャネルと送信番号を含むメッセージレコードから取得されます。`booked`、`contact_created`、および`credits_spent`はイベントストリームから取得されますが、これには送信番号が含まれていないため、`number`でグループ化すると、これらのメトリクスは`null`番号のバケットに分類されます。

| パラメータ | 必須 | 説明 |
|---|---|---|
| `from` | いいえ | 範囲の開始、`YYYY-MM-DD`。デフォルトは30日前です。 |
| `to` | いいえ | 範囲の終了、`YYYY-MM-DD`。デフォルトは今日です。 |
| `metrics` | いいえ | `sent`、`ai_sent`、`human_sent`、`delivered`、`read`、`replied`、`booked`、`contact_created`、`credits_spent`からコンマ区切りで指定したリスト。デフォルトは`sent,replied`です。不明なメトリクスは`400`を返します。 |
| `group_by` | いいえ | `date`、`campaign`、`channel`、`agent`、`number`から最大2つのディメンションをコンマ区切りで指定したリスト。`date`は受け入れられますが、効果はありません。すべてのレスポンスにはすでに時間軸が含まれています。アカウント全体の単一シリーズの場合は省略してください。 |
| `granularity` | いいえ | `day`（デフォルト）、`week`、または`month`。週のバケットは月曜日に始まり、月のバケットは1日に始まります。 |
| `limit` | いいえ | 残りが`other_bucket`に集約される前に返すシリーズの数（1〜50）。デフォルトは12です。 |
| `campaign_id` | いいえ | このキャンペーンに属するアクティビティのみをカウントします。レガシー機能です。`agent_id`の使用を推奨します。 |
| `agent_id` | いいえ | このAIエージェントに属するアクティビティのみをカウントします。 |
| `channel` | いいえ | このチャネル（例：`whatsapp`）でのアクティビティのみをカウントします。 |

このエンドポイントの日付範囲は**92日**に制限されています（このページの他の場所で使用されている366日の上限よりも厳しくなっています）。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}
```

**フィールドに関する注記:**

- `key` — 1つのシリーズの識別子。要求された`group_by`ディメンションのキーのみが存在します。行の値が不明なディメンション（キャンペーンのないメッセージ、チャネルのないイベント）は削除されず、`null`として返されるため、シリーズは合計と一致します。
- `other_bucket` — 何も集約されなかった場合は`null`。
- このエンドポイントは、レポートデータベースがアカウントの回答を生成できない場合、ゼロで埋められた`200`ではなく、`"error_code": "analytics_unavailable"`を含む`503`を返します。ゼロ埋めされたチャートは事実として誤認される可能性があるためです。

---

## 会話の成果

日付範囲全体で会話がどのように終了したかを返します。AIが割り当てた各成果タグの日次カウントに加え、返信、予約、人間への引き継ぎ、およびAIが分類しなかった会話の範囲合計が含まれます。

`GET /analytics/outcomes`

時間軸を集約してタグごとの範囲合計のみを取得するには、`group_by=tag`を渡します。そのモードでは`labels`は空になり、各タグの`counts`配列も空になりますが、`total`には引き続き値が入力されます。

| パラメータ | 必須 | 説明 |
|---|---|---|
| `from` | いいえ | 範囲の開始日、`YYYY-MM-DD`。デフォルトは30日前です。 |
| `to` | いいえ | 範囲の終了日、`YYYY-MM-DD`。デフォルトは今日です。 |
| `campaign_id` | いいえ | 現在このキャンペーンに登録されている連絡先との会話のみをカウントします。レガシー機能です。`agent_id`の使用を推奨します。 |
| `agent_id` | いいえ | このAIエージェントに属する成果のみをカウントします。 |
| `group_by` | いいえ | `date`（デフォルト）は日別のカウントを保持し、`tag`は範囲の合計に集約します。 |

このエンドポイントの日付範囲は**92日**に制限されています。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}
```

**フィールドに関する注記:**

- `by_tag[].tag` — AIが成果タグを割り当てなかった会話の`null`。
- `totals.human_alerted` — 人間に引き継がれた会話。これは引き継ぎのたびに記録され、以前はどのエンドポイントでも表示されていませんでした。
- レポートデータベースが回答できない場合、Metricシリーズと同じ`503`/`analytics_unavailable`の挙動をとります。

---

## ダッシュボードのインサイト

日付範囲に対する完全なダッシュボードのペイロードを1回の呼び出しで返します。曜日・時間別の返信率ヒートマップ、キャンペーンリーダーボード、チャネル別のボリューム、接続ごとの正確な合計、日別のメトリクス内訳（アカウント全体、チャネル別、番号別）、連絡先のソース、受信トレイの応答時間、最近のアクティビティフィードが含まれます。これはAPIの中で最も豊富なレポートペイロードであり、アプリ内のダッシュボードを直接駆動しています。

`GET /analytics/dashboard-insights`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `startDate` | はい | 範囲の開始日、`YYYY-MM-DD`。 |
| `endDate` | はい | 範囲の終了日、`YYYY-MM-DD`。 |
| `campaignId` | いいえ | このキャンペーンに属するアクティビティのみを含めます（`campaign_id`も受け入れ可能）。レガシー機能です。`agent_id`の使用を推奨します。 |
| `agent_id` | いいえ | このAIエージェントに属するアクティビティのみを含めます（`agentId`も受け入れ可能）。エージェントスコープ下では、キャンペーンリーダーボードはそのエージェントのアクティビティのみから構築されます。 |

このエンドポイントは、アプリ内ダッシュボードと実装を共有しているため、`from`/`to`ではなく`startDate`/`endDate`を使用します。範囲は92日に制限されており、それより広い場合は**拒否されるのではなく、クランプ（制限）**されます。

> **Nullはゼロではなく、利用不可を意味します。** いくつかのブロック（`numberStats`、`channelDailySeries`、`metricDailyBreakdown`、`contactsByCountry`）はレポートデータベースから計算され、アカウントに対して回答できない場合は`null`が返されます。`null`ブロックを空のグラフとしてレンダリングしないでください。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**レスポンス**（省略版 — このペイロードは大きいため、完全なスキーマについては[APIリファレンス](reference.md)を参照してください）

```json
{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}
```

**フィールドに関する注記:**

- `heatmap.buckets[].weekday` — `0`は日曜日から`6`は土曜日までです。
- `numberStats`、`channelDailySeries`、`metricDailyBreakdown`、`contactsByCountry`、`ai_human_split` — それぞれ、アカウントに対してレポートデータベースが利用できない場合は個別に`null`となります。他のすべてのブロックは引き続き返されます。

---

## ダッシュボードのAIインサイト

日付範囲におけるアカウントのメッセージングに関する、AIが作成した3つの短いインサイト（1つの成果、1つの注目点、1つのヒント）を返します。これらは、解釈が必要な数値ではなく、レポートにそのまま貼り付けられる文章です。アカウント自身のメッセージメトリクスのみから生成されます。

`GET /analytics/dashboard-ai-insights`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `startDate` | はい | 範囲の開始日、`YYYY-MM-DD`。 |
| `endDate` | はい | 範囲の終了日、`YYYY-MM-DD`。 |

このエンドポイントはアカウント全体に適用されるため、キャンペーンやエージェントのスコープは指定しません。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}
```

`startDate` または `endDate` が欠落している場合、`400` が返されます。

---

## エンティティのアクティビティタイムライン

特定の連絡先、案件、またはタスクのアクティビティを、メッセージ、アポイントメント、メモ、ステータスの変更などを含め、最新のものから順に1つのタイムラインとして返します。複数のリストエンドポイントを組み合わせることなく、「この人物に何が起こったか」を確認するために使用します。

`GET /analytics/entity-activity`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `entityType` | はい | `contact`、`deal`、または `task`。 |
| `entityId` | はい | タイムラインを取得するレコードのID。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}
```

`entityType`/`entityId` が欠落しているか無効な場合、`400` が返されます。アカウント上に存在しないエンティティを指定した場合は `404` が返されるため、他のアカウントのIDを推測することはできません。

---

## 集計イベント数（レガシー）

[メッセージボリュームの概要](#message-volume-summary)と同じ集計イベント数を返しますが、一部の古いインテグレーションで採用されていた camelCase 形式（`contact_created` ではなく `contactCreated`、`by_date` ではなく `byDate`）で返されます。新しいインテグレーションには `/analytics/summary` を使用してください。このエンドポイントは、アプリ内のダッシュボードとAPIで実装を共有するためにのみ存在します。

`GET /analytics/aggregate`

| パラメータ | 必須 | 説明 |
|---|---|---|
| `startDate` | いいえ | 範囲の開始日。ISO日付または日時。デフォルトは `/analytics/summary` が使用する期間と同じです。 |
| `endDate` | いいえ | 範囲の終了日。ISO日付または日時。 |
| `campaignId` | いいえ | このキャンペーンに属するイベントのみをカウントします（`campaign_id` も受け付けます）。レガシー機能のため、`agent_id` の使用を推奨します。 |
| `agent_id` | いいえ | このAIエージェントに属するイベントのみをカウントします（`agentId` も受け付けます）。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}
```

---

## 代理店サブアカウントのロールアップ


---

## Analytics API エラー

Analytics エンドポイントは、標準のエラーエンベロープを返します。

```json
{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}
```

分析エンドポイントにおいて、無効な日付形式や範囲外の期間を指定した場合は `400` が返され、不明な `campaign_id` や `agent_id` を指定した場合は `404` が返されます。また、いずれかを受け付けるエンドポイントで `campaign_id` と `agent_id` の両方を送信した場合も `400` となります（最大1つのみ指定してください）。PG専用のレポートエンドポイント（メトリクスシリーズ、会話の成果、代理店ロールアップ）では、レポートデータベースがアカウントの回答を生成できない場合、ゼロで埋め尽くされた `200` ではなく、`"error_code": "analytics_unavailable"` を伴う `503` が返されます。その場合はしばらくしてから再試行してください。すべてのエンドポイントで返される可能性のある共通コード（`401`、`403`（プランにAPIアクセスが含まれていない、または代理店ロールアップでアカウントが Agency/Dev ではない場合）、`429`（レート制限）、`500`）については、再試行のガイダンスとともに [エラーとページネーション](errors-and-pagination.md) に記載されています。

---

## 次のステップ

- [認証](authentication.md) — リクエストを認証する4つの方法。
- [エラーとレート制限](errors-and-pagination.md) — ステータスコードと300リクエスト/分の制限について。
- [キャンペーンAPI](campaigns.md) — これらの数値でフィルタリング可能なキャンペーン。