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

Scope of Results

Sales agents MUST return every media buy owned by the authenticated account, regardless of how the buy was created — via AdCP create_media_buy, via the seller’s own APIs, via manual trafficking, via legacy or third-party systems. Scope is account ownership, not creation surface. A media_buy_id returned here identifies any order in the seller’s ad server accessible to the authenticated caller. Any media buy returned by get_media_buys MUST be reachable by every task in its valid_actions. Sales agents MUST NOT mark a buy read-only, hide it, or refuse updates on the basis that it was not originally created via AdCP. When an action is unavailable for business reasons (contractual obligations, platform constraints, policy), the seller MUST omit only that action from valid_actions — never the whole set, and never merely because the buy was created outside AdCP. A seller that returns non-AdCP buys with a systematically empty valid_actions is non-conformant; that pattern is indistinguishable from hiding the buy. Sellers that need to partition inventory away from a caller MUST do so at the account boundary, not within-account. See Account Ownership vs. Creation Surface. Request Schema: /schemas/3.0.19/media-buy/get-media-buys-request.json Response Schema: /schemas/3.0.19/media-buy/get-media-buys-response.json

Request Parameters

*media_buy_ids filters results to specific media buys. If neither is provided, the query is scope-based and uses status_filter + pagination. When media_buy_ids 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.

History Entry Object

History entries are append-only — sellers MUST NOT modify or delete previously emitted entries. Callers MAY cache entries by revision number.

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.

Valid Actions Mapping

The valid_actions array tells agents what operations are permitted on a media buy in its current state. Sellers SHOULD include this field. Expected values by status: Sellers MAY omit actions based on business rules (e.g., omit cancel when the media buy has contractual obligations that prevent cancellation).

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_creatives, pending_start, 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) 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