Skip to main content
Retrieve the current operational state of media buys: configuration, creative approval status, missing assets, and optional near-real-time delivery snapshots. Response Time: ~1 second Request Schema: /schemas/latest/media-buy/get-media-buys-request.json Response Schema: /schemas/latest/media-buy/get-media-buys-response.json

Request Parameters

*Either media_buy_ids or buyer_refs can be provided. If neither is provided, the query is scope-based and uses status_filter + pagination. When media_buy_ids or buyer_refs are provided, no implicit status filtering is applied. Pass status_filter explicitly if you want to filter identified buys by status.

Response

Returns an array of media buys with current status, creative approval state, and optionally delivery snapshots:

Media Buy Object

Package Object

Creative Approval Object

Creative revisions are represented as approval_status: "rejected" with a specific rejection_reason. There is no package-level input-required status for creative edits; upload corrected assets via sync_creatives.

Snapshot Object

not_delivering means the package is within its scheduled flight but has delivered zero impressions for at least one full staleness cycle. Implementers must not return not_delivering until staleness_seconds have elapsed since package activation — a new package with no impressions in its first minutes is expected, not a problem. Check start_time to confirm the package is within its flight before acting on this status. Money fields use this currency precedence: snapshot.currency -> package.currency -> media_buy.currency.

Common Scenarios

Check creative approval status

Monitor delivery with snapshots

Campaign readiness check

Snapshot vs. get_media_buy_delivery

Use get_media_buys to answer “what is the current state of my campaigns?” and get_media_buy_delivery for “how did my campaigns perform over a period?” Status taxonomy is shared for lifecycle filters across both tasks (pending_activation, active, paused, completed). get_media_buy_delivery may additionally return reporting-only statuses (reporting_delayed, failed) in webhook contexts.

Data Freshness

Snapshot staleness_seconds varies by platform: When the platform only has batch reporting, the seller agent should return the most recent cached data with the appropriate staleness_seconds. If include_snapshot: true and snapshot is omitted for a package, check snapshot_unavailable_reason:
  • SNAPSHOT_UNSUPPORTED: the seller does not support package snapshots for this integration
  • SNAPSHOT_TEMPORARILY_UNAVAILABLE: snapshot pipeline is delayed or degraded; retry later
  • SNAPSHOT_PERMISSION_DENIED: caller lacks permission to view snapshot metrics for that package

Pagination

Use cursor pagination for broad status queries to avoid large payloads:
  • Request: set pagination.max_results (1-100, default 50) and optional pagination.cursor
  • Response: read pagination.has_more; when true, pass pagination.cursor into the next request
  • ID-targeted queries (media_buy_ids/buyer_refs) can omit pagination unless the ID set is very large

Error Handling

Next Steps

  • Upload missing creatives: Use sync_creatives for formats in format_ids_pending
  • Investigate zero delivery: Check delivery_status: "not_delivering" and start_time to confirm the flight is active, then use update_media_buy to adjust pricing or targeting
  • Detailed reporting: Use get_media_buy_delivery for date-range reporting and daily breakdowns
  • Optimize campaigns: Use provide_performance_feedback to share results with the seller