Get media buy status

​

Request

curl https://api.apostra.com/api/v2/buyer/campaigns/cmp_987654321/media-buy-status \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

​

Parameters

​

Response

{
  "campaign_id": "cmp_987654321",
  "campaign_status": "ACTIVE",
  "operational_status": "active",
  "media_buys": [
    {
      "media_buy_id": "mb_abc123",
      "adcp_media_buy_id": "adcp_mb_001",
      "internal_status": "ACTIVE",
      "adcp_status": "active",
      "operational_status": "active",
      "previous_internal_status": "PENDING_APPROVAL",
      "previous_adcp_status": "pending_start",
      "updated": true,
      "status_refresh_source": "direct_agent",
      "blockers": []
    }
  ],
  "agents_queried": 1,
  "errors": [],
  "blockers": [],
  "pending_creative_reviews": 0,
  "has_upstream_media_buy": true,
  "has_delivery": true
}

• campaign_status — the stored campaign lifecycle status.
• operational_status — the rolled-up delivery status to present to users (draft, pending_creatives, pending_start, active, paused, completed, attention_required, or no_media_buys). A persisted COMPLETED or cleanly CANCELED buy reports completed, unless its seller has not agreed it ended (see When a buy ends) or reports different financial terms (see contract_out_of_line below); attention_required always has a named blocker or reconciliation reason.
• internal_status — Apostra status after this poll (one of DRAFT, PENDING_APPROVAL, INPUT_REQUIRED, ACTIVE, PAUSED, COMPLETED, CANCELED, FAILED, REJECTED, ARCHIVED).
• adcp_status — the raw AdCP media-buy status string currently stored or returned by the status check.
• media_buys[].operational_status — the per-buy delivery status behind the campaign rollup.
• previous_internal_status / previous_adcp_status — values before this poll.
• updated — true only when this request changed Apostra’s stored status. false does not mean the status is stale; it can also mean the buy was already current.
• status_refresh_source — where this media buy’s status signal came from:
  • direct_agent — this request called the sales agent’s get_media_buys.
  • delegated_adapter — this request called the delegated adapter’s get_media_buys.
  • storefront_route_rollup — this request read persisted upstream-leg statuses for a storefront-routed buy. This can confirm active delivery without incrementing agents_queried.
  • not_submitted — the buy has no upstream media-buy ID yet.
  • persisted_terminal — the buy is terminal (COMPLETED, CANCELED, FAILED, or REJECTED) and was read from persisted PRIMARY state without contacting the seller during this request. A COMPLETED buy that no seller reported completed is not read this way: it is checked with the seller on every request, and the seller’s own status replaces it.
  • refresh_failed — the refresh failed before a per-buy status signal was available; see errors and blockers.
• agents_queried — number of direct sales-agent or delegated-adapter status calls made during this request. It can be 0 for a current storefront-routed buy when status_refresh_source is storefront_route_rollup.
• errors — per-media-buy errors from agents that failed to respond; media_buy_id and error message are included for each failure. A partial error does not prevent successful entries from being returned.
• blockers / media_buys[].blockers — campaign-level and per-buy reasons delivery is not ready or needs attention, such as pending creative review, missing upstream IDs, or a seller that has not agreed an ended buy stopped (seller_still_active, seller_end_unconfirmed).
  • not_delivering_after_flight_start — the buy is booked but still not delivering more than 24 hours after its flight started: the seller has not started it, or the seller reports it running and has reported no delivery. See When a buy has not started delivering.
  • seller_paused_not_requested — the seller reports the buy paused, nobody asked for the pause, and the buy’s flight has started. See When a buy has not started delivering.
  • seller_status_unavailable — the buy is live, and the seller’s status and reporting for it are temporarily unavailable because the seller’s connection to its ad server stopped working. The message never names the ad server. The buy reports attention_required for as long as the seller’s failure lasts, and the notice clears by itself when the seller restores the connection. It adds attention only: the buy’s internal_status and has_delivery do not change, and delivery numbers may be late until it clears. The seller has been told. A buy that is not live, such as one that has completed, never carries it.
  • seller_status_unreadable — Apostra has the buy recorded as completed, but the seller never reported it completed, and Apostra cannot read the buy’s status from the seller. The buy may still be running. The campaign-level blockers entry’s message names the seller and the read failure, for example that the seller’s agent is below the AdCP version Apostra supports. The buy reports attention_required for as long as the seller cannot be read, keeps internal_status COMPLETED, and clears by itself once a read of the seller succeeds, at which point the buy takes the status the seller reports. Contact the seller to confirm the current state. A buy the seller reported completed never carries it.
  • contract_out_of_line — the seller’s latest report of the buy differs from the booked contract on budget, rate or flight: for example, the seller reports an earlier or later end date, a different budget, or a different rate. The buy reports attention_required while the difference stays open, from the time the buy is live until 7 days after its flight end, including after it completes. The marker appears only when Apostra can show the two figures differ. It does not appear when the seller reports an amount in a currency the booking does not state, when the booked total includes fees the seller’s packages do not, when the seller split an evenly spread budget differently across packages, or when two geography shapes cannot be shown to reach different areas: those are listed as not comparable. A currency that both sides state and that differs, a moved end date and a rate that differs on a shared currency still show. It adds attention only: the buy’s internal_status and has_delivery do not change. Apostra’s operations team takes the difference up with the seller; it clears when the seller’s report matches the contract again, or when you update the buy so the contract matches what the seller reports.
• pending_creative_reviews — count of creative reviews still waiting.
• has_upstream_media_buy — whether any media buy has an upstream ADCP media-buy ID.
• has_delivery — whether the campaign has an active or completed delivery signal.

​

When a buy has not started delivering

​

When a buy ends

• The seller agrees. The buy becomes COMPLETED, with operational_status: "completed", and checking stops.
• The seller still reports the buy active. If the seller still reports it active more than 24 hours after the end, the buy stays ACTIVE but reports operational_status: "attention_required" with the blocker seller_still_active. The seller may still be delivering. adcp_status shows what the seller last reported. Apostra keeps checking and alerts its operations team.
• The seller never confirms. If the seller has not reported the buy ended 14 days after the end (for example, it still reports it paused or pending, or says nothing), the buy reports attention_required with the blocker seller_end_unconfirmed. Apostra alerts its operations team.

​

Errors

​

Related