/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
Snapshotstaleness_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 integrationSNAPSHOT_TEMPORARILY_UNAVAILABLE: snapshot pipeline is delayed or degraded; retry laterSNAPSHOT_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 optionalpagination.cursor - Response: read
pagination.has_more; when true, passpagination.cursorinto 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_creativesfor formats informat_ids_pending - Investigate zero delivery: Check
delivery_status: "not_delivering"andstart_timeto confirm the flight is active, then useupdate_media_buyto adjust pricing or targeting - Detailed reporting: Use
get_media_buy_deliveryfor date-range reporting and daily breakdowns - Optimize campaigns: Use
provide_performance_feedbackto share results with the seller