始める前に
このガイドでは、Reports API の使用方法について説明します。詳細情報については 概要 そして APIリファレンス.
このトピックでは
アプローチを選ぶ
Reports APIには、アクティビティ記録を取得するための2つのメソッドが用意されており、それぞれ異なるクエリパターンとデータ量に最適化されています。
同期（リアルタイム）
同期的アプローチは、最大数万レコードを検索する頻繁なクエリに最適である。同期リクエストを行うと、レコードはAPIレスポンスで即座に返されるため、リアルタイムのダッシュボードやモニタリング・システムに最適である。この方法は、特定のメッセージやレコードIDによるクエリもサポートしており、個々のトランザクションを調べる必要がある場合に便利である。小規模なデータセットでは効率的ですが、最適なパフォーマンスを維持するために、同期クエリはリクエストあたり数千レコードまでに制限することをお勧めします。
使用例： 特定のキャンペーンの今日のSMS配信状況を取得します。
非同期（バックグラウンド処理）
より大きなデータを必要とする場合、非同期アプローチは、数百万レコードを取得する必要があるような頻繁でないクエリ用に設計されています。この方法では、データをすぐに返すのではなく、バックグラウンドで処理が行われている間に、CSVデータを含むダウンロード可能なZIPファイルを生成します。生成処理には通常、100万レコードあたり5～10分かかります。処理が完了したときに通知を受け取るコールバックURLを提供するか、レポートのステータスを定期的にポーリングすることができます。最適なパフォーマンスを保証するために、Vonageは適切な開始日と終了日を設定することにより、非同期クエリを最大700万レコードに制限することを推奨します。
使用例： すべての音声通話の月次報告書を作成する。
最初のリクエスト
同期リクエストの例
特定の日付範囲のSMSレコードを取得します：
非同期リクエストの例
12月に送信されたすべてのメッセージのレポートを作成します：
認証
すべての Reports API 要求には、API キーとシークレットを使用した HTTP 基本認証が必要です：
交換 $VONAGE_API_KEY そして $VONAGE_API_SECRET からのクレデンシャルを使用してください。 Vonageダッシュボード.
共通パラメータ
これらのパラメータは、ほとんどの Reports API 呼び出しで使用されます：
| パラメータ | 必須 | 説明 | 例 |
|---|---|---|---|
account_id | Vonage APIキー（アカウントID） | abcd1234 | |
product | 問い合わせるVonage製品 | SMS, MESSAGES, VOICE-CALL | |
date_start | 🔸 | 日付範囲の開始日（ISO-8601形式） | 2026-01-01T00:00:00Z |
date_end | 🔸 | 日付範囲の終了（ISO-8601形式） | 2026-01-06T23:59:59Z |
direction | 🔸 | メッセージ/通話方向 | inbound または outbound |
id | 🔸 | 特定のメッセージまたはレコードID（シンクのみ） | 日付範囲との併用不可 |
凡例だ： 常に必須
日付フォーマットの要件
日付はISO-8601形式でなければならない：
- UTCフォーマット：
2026-01-01T00:00:00Z - タイムゾーンオフセットあり：
2026-01-01T08:00:00+0800
重要だ： 使用時 GET を要求する。 + の日付をURLエンコードする：
IDによるクエリと日付範囲によるクエリ
- IDで： 特定のレコードを取得する（同期のみ）
- 日付範囲別： 期間内の全レコードを検索
- 両方は使えない： どちらかを選択する。
idまたはdate_start/date_end両方ではない
製品固有のパラメータ
製品によってサポートするパラメータは異なります。このセクションでは、各製品の必須パラメータとオプション・パラメータの詳細を説明します。完全なパラメータ仕様とレスポンス・フォーマットについては APIリファレンス.
ショートメール
必須パラメータ：
product- に設定する。SMSaccount_id- Vonage APIキーdirection- 以下のいずれかでなければならない。inboundまたはoutbound
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）status- 配送状況によるフィルタリング（例．delivered,failed,expired)from- 送信者番号to- 受取人番号country- 国番号で絞り込むnetwork- ネットワークで絞り込む MCC-MNCclient_ref- クライアント・レファレンスaccount_ref- 口座参照include_message- レスポンスにメッセージ本文を含める (true/false)
例
トラフィック制御
必須パラメータ：
product- に設定する。SMS-TRAFFIC-CONTROLaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用不可）
メッセージ
必須パラメータ：
product- に設定する。MESSAGESaccount_id- Vonage APIキーdirection- 以下のいずれかでなければならない。inboundまたはoutbound
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）status- 配送状況によるフィルタリング（例．submitted,delivered,read,rejected)from- 送信者識別子to- 受信者識別子provider- チャンネルによるフィルター（例whatsapp,sms,mms,viber_service_msg,messenger,instagram,rcs)include_message- レスポンスにメッセージ本文を含める (true/false)
ボイスコール
必須パラメータ：
product- に設定する。VOICE-CALLaccount_id- Vonage APIキー
追加パラメータ：
direction- 呼び出し方向inboundまたはoutbound)date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）status- 通話状況（例．ANSWERED,MACHINE,ERROR)from- 発信者番号to- 発信番号country- 国番号で絞り込むnetwork- ネットワークで絞り込む MCC-MNCcall_id- 特定の呼び出し識別子
イン・アップ・ヴォイス
必須パラメータ：
product- に設定する。IN-APP-VOICEaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）status- 通話終了ステータスconversation_id- 会話IDleg_id- 通話の特定のレグ
VOICE-TTS
必須パラメータ：
product- に設定する。VOICE-TTSaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用不可）
音声失敗
必須パラメータ：
product- に設定する。VOICE-FAILEDaccount_id- Vonage APIキー
追加パラメータ：
direction- 呼び出し方向inboundまたはoutbound)date_start/date_end- レコードをフィルタリングする日付範囲from- 発信者番号to- 発信番号id- 特定のレコードID（日付範囲では使用できません）country- 国コードフィルター
ウェブソケットコール
必須パラメータ：
product- に設定する。WEBSOCKET-CALLaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用不可）
海難救助
必須パラメータ：
product- に設定する。ASRaccount_id- Vonage APIキー
追加パラメータ：
direction- 呼び出し方向inboundまたはoutbound)date_start/date_end- レコードをフィルタリングする日付範囲from- 発信者番号通知to- Numbersと呼ばれるid- 特定のレコードID（日付範囲では使用できません）
AMD
必須パラメータ：
product- に設定する。AMDaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用不可）
Verify-API
必須パラメータ：
product- に設定する。VERIFY-APIaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）to- Verifyされた電話番号network- ネットワークで絞り込む MCC-MNC
Verify-V2
必須パラメータ：
product- に設定する。VERIFY-V2account_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲channel- 検証チャンネル(v2,email,silent_auth)status- リクエスト状況parent_request_id- 親リクエストIDでフィルタリングし、v2検証リクエストと関連する電子メールまたはsilent_authイベントを関連付けます。country- 国コードlocale- 言語/ロケールnetwork- モバイル・ネットワーク・コードto- 検証中の電話番号id- 特定のレコードID（日付範囲では使用不可）
NUMBER-INSIGHT（ナンバー・インサイト
必須パラメータ：
product- に設定する。NUMBER-INSIGHTaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）number- 問い合わせのあった電話番号network- モバイル・ネットワーク・コード
ナンバー・インサイト-V2
必須パラメータ：
product- に設定する。NUMBER-INSIGHT-V2account_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲request_type- 洞察要求のタイプ（例．fraud_score,sim_swap)risk- リスク評価レベルstatus- Numbers インサイトのリクエスト状況swapped- ポート/スワップされた番号かどうかid- 特定のレコードID（日付範囲では使用不可）
カンバセーション・イベント
必須パラメータ：
product- に設定する。CONVERSATION-EVENTaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲conversation_id- 特定の会話IDstatus- イベント状況id- 特定のレコードID（日付範囲では使用できません）
会話メッセージ
必須パラメータ：
product- に設定する。CONVERSATION-MESSAGEaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲conversation_id- 特定の会話IDid- 特定のレコードID（日付範囲では使用できません）
ビデオAPI
必須パラメータ：
product- に設定する。VIDEO-APIaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲session_id- ビデオセッションIDmeeting_id- 会議の識別子id- 特定のレコードID（日付範囲では使用できません）
ネットワーク・アピ・イベント
必須パラメータ：
product- に設定する。NETWORK-API-EVENTaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲product_name- 特定のネットワークAPI製品request_session_id- リクエストセッション識別子product_path- APIプロダクトパスcorrelation_id- 相関IDrequest_type- ネットワークAPIリクエストの種類id- 特定のレコードID（日付範囲では使用できません）
レポート
必須パラメータ：
product- に設定する。REPORTS-USAGEaccount_id- Vonage APIキー
追加パラメータ：
date_start/date_end- レコードをフィルタリングする日付範囲id- 特定のレコードID（日付範囲では使用できません）
注： 全製品対応 include_subaccounts パラメータを使用して非同期レポートを作成し、Subaccountsからのデータを含めることができます。レスポンス・フォーマットとその他のフィルタリング・オプションの詳細については APIリファレンス.
非同期レポートの操作
非同期レポートを作成すると request_id でレポートステータスを追跡する：
回答例
{
"request_id": "ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e",
"request_status": "PENDING",
"direction": "outbound",
"product": "SMS",
"account_id": "abcd1234",
"date_start": "2026-01-01T00:00:00+0000",
"date_end": "2026-01-06T23:59:59+0000",
"_links": {
"self": {
"href": "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"
}
}
}
レポートステータスの確認
を使用する。 request_id をクリックして、レポートの準備ができたかどうかを確認してください：
完成報告書のダウンロード
レポートのステータスが SUCCESSを抽出する。 file_id レスポンスとダウンロードから：
ダウンロードされたZIPファイルには、お客様の記録がCSV形式で保存されています。ファイルは72時間利用可能です。