Skip to main content

Documentation Index

Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt

Use this file to discover all available pages before exploring further.

メディアバイの現在の運用状態（設定、クリエイティブ承認ステータス、不足アセット、オプションのほぼリアルタイム配信スナップショット）を取得します。 応答時間: 約1秒 リクエストスキーマ: /schemas/latest/media-buy/get-media-buys-request.json レスポンススキーマ: /schemas/latest/media-buy/get-media-buys-response.json

​
リクエストパラメータ

パラメータ型必須説明
accountaccount-refいいえアカウント参照。{ "account_id": "..." } または、セラーが暗黙的な解決をサポートしている場合は { "brand": {...}, "operator": "..." } を渡します。省略した場合、アクセス可能なすべてのアカウントのデータを返します。
media_buy_idsstring[]いいえ*取得するメディアバイIDの配列
status_filterstring | string[]いいえステータスフィルター: "active"、"pending_activation"、"paused"、"completed"。media_buy_ids が両方とも省略された場合のみ、デフォルトで ["active"] になります。
include_snapshotbooleanいいえtrue の場合、各パッケージのほぼリアルタイム配信スナップショットを含めます。デフォルトは false。
paginationobjectいいえ広範なクエリのカーソルベースのページネーション制御（max_results、cursor）。
*media_buy_ids は結果を特定のメディアバイに絞り込む。どちらも指定しない場合、クエリはスコープベースとなり status_filter と pagination を使用します。 media_buy_ids を指定した場合、暗黙的なステータスフィルタリングは適用されない。特定のバイをステータスでフィルタリングしたい場合は status_filter を明示的に渡すこと。

​
レスポンス

現在のステータス、クリエイティブ承認状態、オプションの配信スナップショットを含むメディアバイの配列を返します:
フィールド説明
media_buysメディアバイオブジェクトの配列
paginationカーソルページネーションメタデータ（has_more、cursor、オプションの total_count）
errorsタスク固有のエラー（例: メディアバイが見つからない）

​
メディアバイオブジェクト

フィールド説明
media_buy_idセラーのメディアバイ識別子
status現在のステータス（pending_activation、active、paused、completed）
currencyメディアバイレベルの金額に使用する ISO 4217 通貨
total_budgetキャンペーンの合計予算（currency 単位）
creative_deadlineクリエイティブのアップロード期限（ISO 8601）
packagesクリエイティブステータスとオプションのスナップショットを含むパッケージの配列

​
パッケージオブジェクト

フィールド説明
package_idセラーのパッケージ識別子
currencyオプションのパッケージレベルの通貨オーバーライド（デフォルトはメディアバイの currency）
bid_priceオークションベースパッケージの現在の入札価格（パッケージの currency が存在する場合はその通貨、なければメディアバイの currency）
start_timeフライト開始時刻（ISO 8601）。配信ステータスを解釈する前にこれを確認すること。
end_timeフライト終了時刻（ISO 8601）
pausedバイヤーがこのパッケージを一時停止しているかどうか
creative_approvalsクリエイティブ承認状態の配列（下記参照）
format_ids_pendingまだアップロードされていない format_ids_to_provide のフォーマットID
snapshot_unavailable_reasoninclude_snapshot: true であるがこのパッケージのスナップショットが返されない場合の理由コード
snapshotほぼリアルタイムの配信スナップショット（include_snapshot: true の場合）

​
クリエイティブ承認オブジェクト

フィールド説明
creative_idクリエイティブ識別子
approval_statuspending_review、approved、または rejected
rejection_reason却下の説明（approval_status が rejected の場合）
クリエイティブの修正は approval_status: "rejected" と特定の rejection_reason で表現されます。クリエイティブ編集のためのパッケージレベルの input-required ステータスは存在しません。修正済みアセットは sync_creatives を使ってアップロードすること。

​
スナップショットオブジェクト

フィールド説明
as_ofプラットフォームがこのスナップショットを取得した際の ISO 8601 タイムスタンプ
staleness_secondsデータの最大経過時間（秒）。ゼロ配信の解釈に使用します: 900（15分）はゼロが実際の値である可能性が高いことを意味し、14400（4時間）はレポートがまだ追いついていない可能性を意味します。
impressionsパッケージ開始以降の合計インプレッション数
spendパッケージ開始以降の合計支出
currencyspend に対するオプションのスナップショット通貨オーバーライド
clicksパッケージ開始以降の合計クリック数（利用可能な場合）
pacing_index配信ペース（1.0 = 順調、<1.0 = 遅れ、>1.0 = 進みすぎ）
delivery_statusdelivering、not_delivering、completed、budget_exhausted、flight_ended、goal_met
extセラー固有の運用フィールドのためのオプションの拡張オブジェクト
not_delivering は、パッケージが予定されたフライト期間内にあるにもかかわらず、少なくとも1回分の staleness サイクルでゼロインプレッションを記録したことを意味します。実装者はパッケージ起動から staleness_seconds が経過するまで not_delivering を返してはなりません — 最初の数分間インプレッションのない新しいパッケージは想定内であり、問題ではありません。このステータスに基づいて行動する前に、start_time を確認してパッケージがフライト期間内にあることを確認すること。 金額フィールドは次の通貨優先順位を使用します: snapshot.currency -> package.currency -> media_buy.currency。

​
一般的なユースケース

​
クリエイティブ承認ステータスの確認

import { testAgent } from '@adcp/client/testing';
import { GetMediaBuysResponseSchema } from '@adcp/client';

const result = await testAgent.getMediaBuys({
  media_buy_ids: ['mb_12345']
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuysResponseSchema.parse(result.data);

if (validated.errors?.length > 0) {
  throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}

for (const mediaBuy of validated.media_buys) {
  for (const pkg of mediaBuy.packages) {
    // Check for missing creatives
    if (pkg.format_ids_pending?.length > 0) {
      console.log(`Package ${pkg.package_id}: missing formats ${pkg.format_ids_pending.map(f => f.id).join(', ')}`);
    }

    // Check approval states
    for (const approval of pkg.creative_approvals ?? []) {
      if (approval.approval_status === 'rejected') {
        console.log(`Creative ${approval.creative_id} rejected: ${approval.rejection_reason}`);
      } else if (approval.approval_status === 'pending_review') {
        console.log(`Creative ${approval.creative_id} pending review`);
      }
    }
  }
}

​
スナップショットを使った配信モニタリング

import { testAgent } from '@adcp/client/testing';
import { GetMediaBuysResponseSchema } from '@adcp/client';

const result = await testAgent.getMediaBuys({
  status_filter: 'active',
  include_snapshot: true
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuysResponseSchema.parse(result.data);

for (const mediaBuy of validated.media_buys) {
  for (const pkg of mediaBuy.packages) {
    const snap = pkg.snapshot;
    if (!snap) continue;

    if (snap.delivery_status === 'not_delivering') {
      console.log(`Package ${pkg.package_id}: zero delivery (data up to ${snap.staleness_seconds}s old)`);
    } else if (snap.pacing_index !== undefined && snap.pacing_index < 0.8) {
      console.log(`Package ${pkg.package_id}: underpacing at ${(snap.pacing_index * 100).toFixed(0)}%`);
    } else {
      console.log(`Package ${pkg.package_id}: ${snap.impressions.toLocaleString()} impressions, pacing ${snap.pacing_index?.toFixed(2)}`);
    }
  }
}

​
キャンペーン配信準備チェック

import { testAgent } from '@adcp/client/testing';
import { GetMediaBuysResponseSchema } from '@adcp/client';

const result = await testAgent.getMediaBuys({
  media_buy_ids: ['mb_12345']
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = GetMediaBuysResponseSchema.parse(result.data);
const [mediaBuy] = validated.media_buys;
const issues = [];

for (const pkg of mediaBuy.packages) {
  if (pkg.format_ids_pending?.length > 0) {
    issues.push(`Package ${pkg.package_id}: ${pkg.format_ids_pending.length} format(s) not yet uploaded`);
  }

  const rejected = (pkg.creative_approvals ?? []).filter(a => a.approval_status === 'rejected');
  if (rejected.length > 0) {
    issues.push(`Package ${pkg.package_id}: ${rejected.length} creative(s) rejected`);
  }
}

if (issues.length === 0) {
  console.log('Campaign ready to launch');
} else {
  console.log('Campaign has blocking issues:');
  issues.forEach(issue => console.log(`  - ${issue}`));
}

​
スナップショットと get_media_buy_delivery の比較

get_media_buys（スナップショットあり）get_media_buy_delivery
目的運用モニタリングレポーティングと照合
鮮度数分（エンティティレベルの統計）数時間（バッチレポートジョブ）
精度ベストエフォート権威ある請求グレード
日付範囲常に「キャンペーン開始以降」設定可能な期間
日別内訳なしあり
クリエイティブステータスありなし
不足アセットありなし
「現在のキャンペーン状態は何か？」という質問には get_media_buys を使い、「ある期間にキャンペーンがどのように機能したか？」には get_media_buy_delivery を使うこと。 ステータスの分類は両タスクのライフサイクルフィルター（pending_activation、active、paused、completed）で共有されています。get_media_buy_delivery はウェブフックコンテキストで追加のレポーティング専用ステータス（reporting_delayed、failed）を返すことがあります。

​
データの鮮度

スナップショットの staleness_seconds はプラットフォームによって異なる:
プラットフォームの種類典型的な staleness_seconds
エンティティレベルの統計（例: GAM LineItemService）900（15分）
ほぼリアルタイムのインサイト API60〜300
バッチ専用レポーティング14400（4時間）
プラットフォームがバッチレポーティングのみの場合、セラーエージェントは適切な staleness_seconds を設定して最新のキャッシュデータを返すべきです。 include_snapshot: true でパッケージの snapshot が省略されている場合、snapshot_unavailable_reason を確認すること:
  • SNAPSHOT_UNSUPPORTED: セラーがこの統合でパッケージスナップショットをサポートしていません
  • SNAPSHOT_TEMPORARILY_UNAVAILABLE: スナップショットパイプラインが遅延または低下しています。後でリトライすること
  • SNAPSHOT_PERMISSION_DENIED: 呼び出し元がそのパッケージのスナップショットメトリクスを閲覧する権限を持っていません

​
ページネーション

大きなペイロードを避けるため、広範なステータスクエリにはカーソルページネーションを使用すること:
  • リクエスト: pagination.max_results（1〜100、デフォルト50）と オプションの pagination.cursor を設定します
  • レスポンス: pagination.has_more を読み取り、true の場合は pagination.cursor を次のリクエストに渡します
  • ID指定クエリ（media_buy_ids）は、IDセットが非常に大きい場合を除きページネーションを省略してよいです

​
エラーハンドリング

エラーコード説明対処法
MEDIA_BUY_NOT_FOUNDメディアバイIDが存在しないmedia_buy_id を確認すること
CONTEXT_REQUIREDリクエストされたスコープにメディアバイが見つからない有効なIDや参照を指定するか、status_filter/ページネーションのスコープを広げること
AUTH_REQUIRED認証が必要認証情報を提供すること

​
次のステップ

  • 不足クリエイティブのアップロード: format_ids_pending のフォーマットには sync_creatives を使うこと
  • ゼロ配信の調査: delivery_status: "not_delivering" と start_time を確認してフライトがアクティブであることを確かめ、次に update_media_buy を使って価格やターゲティングを調整すること
  • 詳細レポーティング: 日付範囲レポーティングや日別内訳には get_media_buy_delivery を使うこと
  • キャンペーンの最適化: セラーに結果を共有するには provide_performance_feedback を使うこと