Skip to main content
This page explains what Apostra checks about a sales agent before it sends the agent buyer work, and how to fix each finding. Every finding on the agent read (get with kind: "agent") links to a section here. It is for the developer of the agent. Connect an agent in an Agents account lists every finding code and what it means. We use evidence from our own calls to your endpoint: the get_adcp_capabilities, sync_accounts and get_products calls we make, and the requests we send while discovering inventory and handling buys. We measure the response your agent sends, its timing, its task progress and whether the products it returns honour the request. A self-reported claim is not proof. How certification works explains what makes an agent ready, what each use case judges and what every result means.

Required declarations

Transport

What it is. Your Agent can use MCP over Streamable HTTP or A2A. For MCP, one application/json response to each request is enough; server-sent events (SSE) are not required. Serverless hosts such as AWS Lambda can serve your Agent. For operations that support asynchronous work, return a task with submitted or working status; we can read its status or receive a push notification when it finishes, without your Agent holding the request open. Why buyers care. A reachable Agent that answers requests lets buyers find inventory, book buys and receive updates, even when work takes longer to finish. How we measure it. We call your Agent to read its capabilities and products, and during certification and buyer work. We check the responses and task progress we receive. Create and update buy requests have a 90-second timeout. The default for product discovery is 45 seconds for the whole call, including connection setup; a buyer can request a different time budget.

AdCP 3

What it is. Your get_adcp_capabilities response must include major version 3 in adcp.major_versions. List the releases you speak in adcp.supported_versions as releases, such as "3.2", not as patch versions such as "3.2.8"; see Release versions. Responses must validate against the schema for the version we negotiate. Why buyers care. A buyer needs the same contract that your Agent says it supports, so a discovery result or buy does not fail when it reaches your system. How we measure it. We call your capabilities endpoint and validate the responses we receive at the negotiated version. Which release we call you on. Unless a request needs a later release that your Agent lists in adcp.supported_versions, we call your Agent on AdCP 3.1, or on 3.0 if your Agent lists 3.0 and not 3.1. An Agent that lists AdCP 3.2 and no 3.0 or 3.1 release is called on 3.2. AdCP 3 is enough to certify today. From 1 February 2027, four capabilities become required. Canonical creative formats need AdCP 3.1 or later, and the compact lifecycle needs AdCP 3.2 or later. So if you are updating your Agent now, build on AdCP 3.2 and you will upgrade only once; see Which AdCP release should I build on?. See Getting ready for AdCP 4.0 for the schedule, the checks we run and what to change.

A supported billing model

What it is. Declare agent, operator, or both in supported_billing. This is a seller-wide declaration, selected for each account in sync_accounts. We review advertiser billing case by case. Why buyers care. The billing model determines who can operate the buy and settle it without a manual intervention after the buyer is ready to transact. How we measure it. We read the billing declaration from the account and capability responses we call, rather than relying on a separate statement from your team. We then check that your Agent accepts the billing models it declares: a sync_accounts request for a declared model that your Agent refuses shows as a Declarations match behaviour finding.

Answer get_adcp_capabilities

What it is. Your Agent must answer get_adcp_capabilities every time we ask. Everything else we read about your Agent starts from that response: which tools it offers, whether it declares the change feed, and which buying modes it serves. Why buyers care. When we cannot read your capabilities we cannot tell whether your Agent announces changes to buys, so we cannot subscribe to its change feed. We read your buys on a schedule instead, and a change can reach buyers later. How we measure it. We read your capabilities about once an hour. Every 15 minutes we reconcile your change-feed subscription from the latest successful read, without calling your Agent again. When no read has succeeded in the last 24 hours, the reconcile asks your Agent itself. After repeated failed reads the source carries a change_feed_capabilities_unavailable finding with you as the owner, and its change-feed check reads as not measured rather than passing. What happens when it is missing. Nothing is switched off: buyers keep discovering and buying. The finding clears on the first read that succeeds. Make get_adcp_capabilities return a valid response, and the next reconcile pass reads it.

Takes buyer account requests

What it is. Your Agent must list both sync_accounts and list_accounts. Buyers declare their own accounts: sync_accounts receives a buyer’s account request, and list_accounts lets us read the result back. Operator authentication. Behind a storefront, Apostra calls your Agent with the credential you connected, for every buyer, so the storefront is the operator. An Agent that sets account.require_operator_auth: true is certified, goes live and is billed on that credential like any other Agent, and buyers are never asked to link an account of their own for it. Your Agent still decides which of its accounts each buyer uses: you map each buyer account to one of your Agent’s accounts in Buyer Account Mapping. A buyer who connects their own credential to your Agent, for example on a pass-through storefront where your Agent is the seller, keeps operator authentication as before. Apostra decided this on 19 November 2026 (AI-22335). How we name the account on later calls. It depends on what your Agent declares:
  • With account.require_operator_auth: false, your accounts are buyer-declared, so AdCP names each one by the buyer’s brand and operator (with sandbox: true for a sandbox account). We send brand and operator, never an account_id, on get_products. On create_media_buy and sync_creatives we send the account_id your sync_accounts returned until your Agent refuses it with INVALID_REQUEST on account.account_id. We then retry that call once with brand and operator, and keep using them for that call.
  • Otherwise we send the account_id your sync_accounts returned, or brand and operator when it returned none.
We read that account_id from the account’s row in your sync_accounts response, where AdCP 3.1 puts it. A row that names the account only on its account reference, as AdCP 3.2 does for settings-update results, is read the same way. A row that carries neither leaves the account without an id, and we send brand and operator on every call. Why buyers care. Every buy runs on an account. A buyer can only start buying from you once your Agent can open an account for them. How we measure it. We read the tool list from your get_adcp_capabilities response, and read it again every hour. The Agent page shows the result as Takes buyer account requests in its required capability declarations. If we have not been able to read your capabilities for more than a day, the page says how long ago we last checked rather than presenting the result as current. If either tool is missing from the stored tool list, the finding names the missing tool or tools and tells you what to declare. An HTTP 401 on list_accounts or sync_accounts contradicts require_operator_auth: false; see Account auth declaration finding. When we cannot read your capabilities. We do not assume your Agent accepts the connected credential for every buyer. A buyer whose advertiser has no account linked for your Agent is refused when it buys, updates, cancels or checks status, until the buyer links an account or we have read capabilities that say operator authentication is not required. If we cannot read the stored capabilities at all, the operation fails with the retryable SERVICE_UNAVAILABLE error instead. What the buyer sees for each operation is listed in the errors reference. What happens when it is missing. When your Agent is the only source behind a storefront, we cannot open an account for a new buyer, so:
  • Certification skips with seller_sandbox_account_failed, because it sets up its test account the same way.
  • An advertiser that does not already have an active account with you no longer sees your products in discovery and cannot book with you.
  • Advertisers whose accounts you already accepted keep discovering and buying as before.
Add both tools and refresh your Agent’s capabilities to open your storefront to new buyers again.

Takes buy corrections

What it is. Your Agent must list update_media_buy in the tools it returns from get_adcp_capabilities, and run it as AdCP defines it. That includes the optional fields of the request. push_notification_config and the version field on the request envelope are optional: an Agent that does not send task webhooks ignores push_notification_config and lets the buyer poll tasks/get, and never refuses an otherwise valid update because the field is present. Apostra does not send push_notification_config on an update to an Agent that lists tasks_get or get_task_status in its tools: it reads a task that finishes later by polling instead. An Agent that lists neither is sent the field, because a webhook is then the only way Apostra learns that its update finished. Live certification is the exception: its pause and resume always carry push_notification_config, so every Agent is judged on accepting it. An Agent that refuses the update because of that field, or of the version field, fails the use case, and the result names the field. Why buyers care. A buy is rarely right the first time. Packages are removed, flight dates move and creatives change after booking. Without update_media_buy the only way to correct a buy is to ask the seller to change it by hand. How we measure it. We read the tool list from your get_adcp_capabilities response, and read it again every hour. The Agent page shows the result as Takes buy corrections in its required capability declarations. A tool you list and then refuse is a separate finding, Declarations match behaviour, which reads the answers to our real calls. What happens when it is missing. Certification skips every use case with seller_update_media_buy_unsupported, and the Agent page shows the finding declaration.update_media_buy as blocking. Nothing changes for buys already booked through your Agent. Implement update_media_buy, list it in your tools and refresh your Agent’s capabilities. If a change needs a new quote, such as an end date past the approved flight, answer REQUOTE_REQUIRED, which says the operation ran.

Declare your buying modes

What it is. Declare media_buy.buying_modes in get_adcp_capabilities, and list exactly the paths your Agent serves: An Agent connected to a Storefront as an inventory Source must declare wholesale: a brief-only Agent plays the storefront role, not the inventory role. See the wholesale catalog published finding. That finding is report-only today. Declare only the paths your Agent serves: certification tests every path in your Agent’s product mode. A value other than brief or wholesale (refine, for example) does not give your Agent a product mode. Why buyers care. A buyer’s request goes down one of these two paths. The declaration is how Apostra knows which requests your Agent can answer, so a buyer is not sent a brief your Agent cannot compose or asked to pick from a catalogue it does not have. How we measure it. We read media_buy.buying_modes from the capabilities your Agent returns. We raise this finding when the declaration is missing, is empty, or lists neither brief nor wholesale. What it means for you. Apostra takes your Agent’s product mode from this declaration. Every Source your Agent serves runs every path it declares. If it has no usable declaration, the finding appears on the Agent page and is report-only. A Source whose Agent has no product mode at all is never called. Apostra leaves that Source out of buyers’ discovery on its own, and your Storefront’s other Sources keep serving buyers. Your Storefront answers “This Seller is temporarily unavailable” only when none of the Sources a request reaches has a product mode. Apostra serves a wholesale catalogue only while your Agent offers it. If your Agent stops declaring wholesale, Apostra stops reading the catalogue and removes the one it last read, so buyers no longer see products it cannot place a buy against. This happens within a few hours of the change: your next capabilities read, then the next catalogue check. When you declare wholesale again, the next catalogue check reads your catalogue and the products return. Archiving a source, or its Storefront, does the same: its products stop appearing to buyers at the next check and are not read again unless you restore it. How to fix it. Add media_buy.buying_modes to your get_adcp_capabilities response with the paths you serve, for example ["brief", "wholesale"]. Apostra re-reads your capabilities every hour, and the finding clears on the next read.

Catalogue reads and rate limits

Apostra reads your wholesale catalogue about once an hour, or every 15 minutes with a conditional read when your Agent returns a wholesale_feed_version. It asks for 100 products a page, so answering with smaller pages means more requests for the same catalogue. A read follows at most 50 pages. When a read of your catalogue fills all 50 pages and your Agent returns no wholesale_feed_version, Apostra reads it in full only about once a day (about every 20 hours), so a full read costs your Agent 50 or more requests once a day, not every hour. Between those reads, buyers see products up to that old. Any one of these keeps your catalogue fresh:
  • Return a wholesale_feed_version. Apostra then checks every 15 minutes with a conditional read, which costs one request when nothing changed.
  • Send catalogue changes. Declare wholesale_feed_webhooks in get_adcp_capabilities and send its change events to the catalogue webhook Apostra registers through sync_accounts. Apostra reads your catalogue as soon as an event arrives.
  • Return full pages. Answer with the 100 products a page Apostra asks for. A catalogue that fits in fewer than 50 pages is read hourly.
If your Agent rate-limits a catalogue page (HTTP 429, or an AdCP RATE_LIMITED error), Apostra waits the Retry-After you send, or 2 seconds when you send none, before each remaining page of that read. If you ask for more than 30 seconds, Apostra stops the read, calls your Agent again only after the time you named, and tries the catalogue at the next hourly check. Apostra reads every page of one catalogue read on one MCP session. If your Agent ends that session part-way through (MCP’s HTTP 404 for an unknown session), Apostra opens a new session and asks for that page once more. A page that fails again ends the read. If your Agent runs on several servers, make sure any of them can serve a session, or keep a session on the server that opened it.

Headers Apostra adds to its requests

Every request Apostra sends your Agent carries the credentials and headers you configured for it, standard HTTP and MCP headers, and these three headers of its own:
  • traceparent: a W3C trace context. Log it to join your records of a call to ours.
  • x-request-id: the id of the request or background job that made the call.
  • x-scope3-debug-id: the debug id Diagnostics shows for the call. Quote it when you ask us about one.
When your Agent asks for signed requests, each request also carries the signature headers described in Verifying our signed requests. Apostra adds no other headers. In particular, it sends no error-monitoring headers such as sentry-trace or baggage.

Declare the targeting you honour

What it is. Declare the account-wide targeting your Agent honours in get_adcp_capabilities, under media_buy.execution.targeting: the fields (for example geo_countries, geo_regions, geo_metros, geo_postal_areas or language), and for fields with systems or values, the ones you support (for example the metro systems you take). Why buyers care. A buyer can send structured targeting with a discovery request. A storefront sends each account-wide field only to an Agent on AdCP 3.2 or later that declares it, so your products, pricing and forecasts are scoped to what the buyer asked for. When your Agent declares its targeting but leaves out a field the buyer sent, or does not support the values asked for, the storefront leaves your products out of that buyer’s answer and tells the buyer why. How your discovery targeting reaches sellers describes this from the buyer’s side. How we measure it. Each time storefront discovery leaves your Agent’s products out for this reason, we count it against the targeting field. We raise the finding declaration.discovery_targeting when your Agent was left out at least once in the last 14 days. It names the fields and how often each one left you out. What it means for you. Buyers who ask for that targeting do not see your products. The finding is advisory: it does not stop certification or buying. An Agent that declares no targeting at all is not left out; its products are returned without forecasts scoped to the buyer’s targeting. How to fix it. For each field you can honour, add it to media_buy.execution.targeting in your get_adcp_capabilities response, with the values you support. Declare only what you honour: a field you declare is sent to you, and a buy that uses it expects you to apply it. A field you cannot honour needs no change. Apostra re-reads your capabilities every hour, and the finding clears once 14 days pass without your Agent being left out. Shows you let buyers choose. A product that sets collection_targeting_allowed: true tells buyers they may buy some of its collections (shows) with collection_selection or collection_list, and your Agent must book exactly that selection. Set it only when your ad server can book a subset of the product’s collections. Otherwise leave it false and sell a single show, or a run of its episodes, as its own product. Apostra’s embedded sales agent cannot book a show selection on any ad server it supports today, so it refuses true.

Takes creatives

What it is. A sales Agent must offer a way to take a creative. AdCP gives two: a creative library the buyer syncs to with sync_creatives, or creatives sent inline on create_media_buy. List sync_creatives in your tools, or allow creatives inline by not declaring media_buy.features.inline_creative_management: false. Why buyers care. A buy cannot go live without a creative. An Agent that takes neither gives a buyer nothing to send, so every campaign they book through it stalls. How we measure it. We read the capabilities your Agent returns, every hour. We raise the finding declaration.creative_transport when your Agent lists no sync_creatives (or declares no creative library) and also declares media_buy.features.inline_creative_management: false. An Agent whose tool list Apostra has not stored yet is shown as not yet observed rather than failing. What it means for you. The finding shows on the Agent page and is reported only for now: it never becomes the headline. Certification sends its test creative with sync_creatives, so it skips every family of an Agent that lists none, as seller_sync_creatives_unsupported. It does the same for an Agent that lists the tool but answers a sync_creatives call with “Tool sync_creatives not found”. An Agent that allows inline creatives but lists no sync_creatives is skipped the same way, because certification does not send creatives inline yet. How to fix it. Implement sync_creatives as AdCP defines it and list it in the tools get_adcp_capabilities returns. If you declare creative.has_creative_library, set it to true. Apostra reads your capabilities again within the hour and the next run buys the families it skipped.

Declare how audiences reach you

What it is. If your Agent declares audience targeting, a buyer must have a way to send it an audience. AdCP declares audience support with one block, media_buy.audience_targeting in get_adcp_capabilities. Its presence says your Agent supports audience targeting, including sync_audiences and audience_include and audience_exclude in a package’s targeting. Declare the block and offer sync_audiences together. Why buyers care. A buyer who wants to reach or leave out an audience on your products reads your declaration to learn whether they can. An Agent that declares audience targeting and has no way to receive an audience gives them a promise they cannot use: there is nothing to send, so the buyer’s targeting has nowhere to land. How we measure it. We read the capabilities your Agent returns. AdCP does not define audience_include or audience_exclude under media_buy.execution.targeting, but many Agents declare them there, and Apostra reads them as a declaration of audience targeting. We raise the finding declaration.audience_targeting when your Agent declares audience_include or audience_exclude as true in media_buy.execution.targeting, and offers neither of these:
  • sync_audiences in its tool list.
  • A media_buy.audience_targeting block.
An Agent that declares neither targeting key is not raised. An Agent whose tool list Apostra has not stored yet is shown as not yet observed rather than failing. What it means for you. The finding shows on the Agent page and is reported only. It does not stop certification or buying, and it never becomes the headline. How to fix it. Choose the one that is true of your Agent:
  • It takes audiences. Declare media_buy.audience_targeting in get_adcp_capabilities, and implement and list sync_audiences. Declaring the block is the AdCP-correct way to say so, and it is the declaration to keep once you have it.
  • It does not take audiences. Stop declaring audience_include and audience_exclude in media_buy.execution.targeting, so buyers are not told they can target an audience on your Agent.
Apostra re-reads your capabilities every hour, and the finding clears on the next read.

Take a buyer’s audience, report it honestly and keep or refuse it

What it is. If your agent declares media_buy.audience_targeting, a buyer can send it an audience with sync_audiences and target it on a package with targeting_overlay.audience_include. Three things follow, all from AdCP:
  • Report an honest status. Return each audience with an audience-status (enums/audience-status.json): processing, ready, too_small or suspended. Never report ready while matched_count is below minimum_size: AdCP says a seller MUST emit too_small in that case. When the status is too_small, populate minimum_size.
  • Keep or refuse the include. A create_media_buy whose package carries audience_include is either accepted, and then get_media_buys returns the package with the audience still in targeting_overlay.audience_include, or refused. Do not accept the buy and drop the audience.
  • Refuse a too-small audience with AUDIENCE_TOO_SMALL. Carry the details shape AdCP recommends, error-details/audience-too-small.json: error.details.current_size and error.details.minimum_size, both numbers. AdCP calls this shape recommended; Apostra expects it so a buyer knows how many more members to add.
Why buyers care. A buyer who sends a first-party audience and targets it expects the campaign to reach that audience. An audience marked ready that cannot be targeted, or an include that is accepted and silently ignored, spends the buyer’s money outside the audience they chose, and nothing tells them. How we measure it. A report-only certification use case, Buyer’s own audience, with three checks: sync accepted, status is honest, and targeting kept. It checks against the pinned AdCP schemas for sync_audiences, audience-status, targeting and audience-too-small. It does not yet judge delivery. What it means for you. The result shows beside your other use cases and does not decide certification or stop any buy. Apostra will announce a date before it counts. How to fix it. Report too_small with minimum_size instead of ready for an audience below your minimum. Return AUDIENCE_TOO_SMALL with current_size and minimum_size when a buy targets such an audience. Return the audience in audience_include when you read back a buy you accepted. If your agent cannot take audiences, stop declaring media_buy.audience_targeting.

Deleting an audience stops the packages that use it

What it is. When Apostra deletes an audience on your Agent, by sending sync_audiences with delete: true for it, every package that targets it in audience_include or excludes it in audience_exclude must stop serving. Do not keep a package serving with the deleted audience dropped from its targeting. AdCP defines the delete as removing the audience from the account; it does not yet say what happens to the packages that use it, so this is Apostra’s requirement. Why buyers care. Apostra deletes an audience on your Agent when the buyer removes it or withdraws their consent to share it with you, and it relies on the delete to stop every package that uses it. A package that keeps serving after its excluded audience is deleted reaches exactly the people the buyer asked to leave out. A package that keeps serving after its targeted audience is deleted spends outside the audience the buyer chose. How we measure it. A certification check, for an Agent that declares a partner route for audiences (media_buy.audience_activation in experimental_features, with a route in media_buy.audience_targeting.supported_activation_methods). See Deleting an audience stops delivery. What it means for you. Before Apostra binds a buyer’s partner-source audience (a shared dataset or a distributed segment) to your Agent in production, your Agent must pass this check. How to fix it. When you receive delete: true for an audience, stop every package whose targeting names that audience, whether it includes or excludes it. Report each one with canceled: true on your next get_media_buys read. If your Agent cannot stop such a package, refuse the delete with an error instead of deleting the audience and leaving the package serving.

Creative formats we supply

What it is. At least one Product must declare a format. It can declare a canonical format_options[].format_kind that we support (display_tag, audio_daast, image, html5, audio_hosted, video_hosted, video_vast, agent_placement, native_in_feed, or image_carousel), or legacy format_ids. For audio_daast, certification buys with a DAAST 1.0 tag that Apostra writes and that plays Apostra’s own test audio. Why buyers care. A buyer can only place a buy if Apostra can deliver a creative that the Product accepts and can measure. How we measure it. We inspect the Products returned by our own get_products calls. A Product that declares both format_options and format_ids must declare the same formats in each; see Keep your two format lists in agreement.

Creatives sent before a buy

What it is. A buyer can send a creative to your storefront before booking a buy with you. Apostra then calls sync_creatives on your Agent with that creative and no assignments, on the buyer’s account with you, and again for each new version the buyer saves. When the buyer takes your storefront off the creative, or archives the creative, Apostra withdraws the review it asked of you, unless a buy with you still carries the creative. Apostra sends your Agent nothing to delete the creative, because AdCP has no call that removes one creative, so a creative already in your library stays there. Why buyers care. Your review can finish before the buyer books, so the buy can start on time. Your answer for each creative is shown to the buyer. What it means for you. If your Agent keeps a creative library, declare creative.has_creative_library: true, list sync_creatives, take the sync as you would any other, and answer with each creative’s review status. If it takes a creative only as part of a buy, declare creative.has_creative_library: false in get_adcp_capabilities. Omitting the field has the same meaning because AdCP defaults it to false. A buyer who names your storefront is then told it takes creatives only with a buy. Apostra books first and sends the creative afterward with the returned media-buy and package assignments, while continuing to track your review status.

Behaviour findings and how to fix them

Each row in the Agent’s Agent-wide behaviour list links to one section below. Every section gives the threshold, the usual causes, and the next step. We apply each threshold to every Source bound to the Agent separately, over its own seven days. The Agent-wide row shows the worst result among those Sources and adds up their counts. So “20 handoffs were still unfinished across one Source” means that Source has 20, not that the Agent has 20 in total. Open Source detail to see which Source needs work. We judge the calls on two kinds of Source: an active Source, and a pending Source of your own organization whose health is not failing. The pending kind is the Source certification runs through, so the findings are there while your agent is being certified. A finding on a pending Source stops nothing: a blocker there stops no buy and leaves a certification pass alone. Once the Source is active, the same finding counts as it does on any active Source. One finding looks further: Discovery brief accepted also judges a pending Source of your own organization whose health is failing, and judges only that finding there, because refusing a valid discovery brief is what makes a Source’s health fail. Every other finding stays not checked on that Source until its health stops failing. A finding that says Not yet evaluated (not checked yet in the findings list) is neither passing nor failing. Its What we saw says why:
  • No matching calls. None of the calls or reports its section names happened in the last seven days. It clears once one does.
  • Waiting for the first evaluation. A Source is first evaluated within an hour of becoming one we judge.
  • No Source we judge. None of the agent’s Sources is active or a pending Source of your own organization whose health is not failing, so none of its calls are judged. Once one is, the next evaluation judges the calls from the last seven days. The certification findings say what that Source needs.
A finding can also say Not read this run (not read in the latest refresh in the findings list). Apostra could not read its evidence in the latest refresh because the read took too long, so it is not judged on that refresh. It is tried again on the next refresh and needs nothing from you. It never counts as a pass, and a blocker found earlier stays a blocker until a refresh reads it again.

Responsiveness finding

Threshold. For each Source, over seven days:
  • Blocker: more than 5% of at least 20 get_products calls timed out. A call times out when it returns neither a result nor a task handle before the response deadline. By default that deadline is 45 seconds, counted from the moment we send the request. A buyer can set a shorter or longer budget. A request_proposals round runs in the background, so its calls to your Agent allow 90 seconds for a result or a task handle. When your storefront passes the brief straight to your Agent, which it does when none of its Agents has a ready wholesale catalogue, and your Agent returns a task handle within that time, the round keeps polling the task for up to 5 minutes from the start of its attempt. A storefront that also sells wholesale products builds its answer within the 90 seconds.
  • Flag: the p95 time to answer get_products is over 10 seconds, and at least one call that took more than 10 seconds returned no task handle.
Usual causes.
  • The Agent builds the whole catalog during the request, for example by calling the upstream ad server live on every get_products.
  • The upstream ad server is slow or rate limiting the Agent.
  • Connection setup and cold starts use part of the deadline.
  • The Agent does not use a task handle, so a slow request can only succeed or time out.
Next step. Find the slow or timed-out get_products calls in your own logs for the window. If the Agent cannot answer within about 10 seconds, return submitted or working with a task handle straight away and finish the work in the background. Where you can, serve the catalog from a cache you refresh on a schedule.

Delivery-read responsiveness finding

Threshold. For each Source, over seven days. This finding is report-only for now: it never blocks certification or buying.
  • Blocker: more than 5% of at least 20 get_media_buy_delivery calls timed out. The deadline is 30 seconds.
  • Flag: the p95 time to answer is over 15 seconds, and at least one call that took more than 15 seconds returned no task handle. A delivery read builds a report, and 15 seconds is half our deadline, so this flag means the Agent is at risk of our timeout.
  • With no delivery reads, the finding is not judged.
Usual causes. The Agent builds the report during the request, waits on a slow upstream service, or does not return a task handle for slow work. Next step. Answer at once with a submitted or working task handle and finish in the background, or serve delivery prepared ahead of time.

Async completion finding

Threshold. A handoff is stale when your Agent answered submitted, working or pending, and five minutes after our request it had not reported a final status. Per Source: one or two stale handoffs is a flag; three or more is a blocker. The five minutes is fixed today and is not a per-task deadline you can set. A final status is completed, failed, rejected, canceled or input-required. A working update does not count. A task that finishes late stops counting at the next evaluation, once we have recorded its final status. Usual causes.
  • The job was lost after the Agent returned the task handle, for example because of a restart, a deploy, or a queue that drops work.
  • The Agent finished the work but never recorded the final status where polling reads it, or never sent it to the webhook.
  • The webhook call failed, for example on a wrong URL or an expired credential, and was not retried.
  • The work routinely takes longer than five minutes and only sends working updates.
Next step. List the task ids that were still open after five minutes in your own logs. For each, check that a final status is stored and that polling returns it. Check that the webhook call succeeds, and retry it when it fails. If a job needs longer than five minutes, it still counts as stale until it reports a final status, so report input-required, failed or completed as early as you can rather than only working.

Call success rate finding

Threshold. Over seven days, for each Source, the share of our calls that failed for a reason other than a timeout. A call fails when your Agent returns an error, rejects the request, or cancels it. A call Apostra stops itself, such as one its own governance refuses, never counts against your Agent. A call that runs past Apostra’s time limit counts as a timeout. Flag above 5%. Blocker above 20%, or when every call failed. This finding is Not yet evaluated until we have made at least one call. This rate counts only calls your Agent answered. A call that got no response, because the connection was refused or reset or nothing answered in time, is not in it. Stays reachable judges those calls, so an Agent that is down is flagged there. Usual causes.
  • Validation that is stricter than AdCP, so your Agent rejects a valid request.
  • Credentials for the upstream ad server that have expired or lost access.
  • An account that does not exist or is not active on your side.
  • An unhandled error inside the Agent, returned as a server error.
Next step. Group the failed calls in your own logs by error code and fix the most common one first. A single rejected field or an expired credential usually explains most failures.

Honours request finding

Threshold. We do not calculate this finding yet, so it never shows Flag or Blocker today. When we do, any breach will be a flag and three or more within the seven days will be a blocker. Usual causes. Products returned outside the property list, channels or countries we sent, for example because the Agent ignores a filter it does not support but did declare. Next step. No action is needed for this finding today. Make sure returned Products respect the property list, channels and countries in each request, and that you declare only the targeting you honour. To read a property list, see Resolve the property lists we send.

Account references resolve to one account finding

Threshold. Per Source: ACCOUNT_AMBIGUOUS returned once or more is a flag. It is a blocker when it appears on three or more separate days in the seven days. Usual causes.
  • Two accounts on your side share the same brand domain and operator, often because sync_accounts created a duplicate (see Account sync is idempotent finding).
  • The lookup matches on brand alone and ignores the operator or the sandbox flag.
Next step. Merge or deactivate the duplicate accounts so each key matches one account. Unless your Agent declares account.require_operator_auth: false, you can also return an account_id on each account from sync_accounts; we then address the account by id instead of brand and operator (see Takes buyer account requests).

Payment terms finding

Threshold. Counted for accounts we requested with agent billing and payment_terms. A missing billing or payment_terms, or an existing account kept on different terms, is a flag. So is a request that carried payment_terms and was refused without saying the terms are the cause: with an error code AdCP does not define, or with UNSUPPORTED_FEATURE, INVALID_REQUEST or VALIDATION_ERROR. A new account returned active on different terms is a blocker. The full rules are in Return and honour payment terms on agent-billed accounts. Usual causes.
  • The Agent gives every new account its own default terms and ignores the terms we request.
  • The account API your Agent calls cannot store payment terms.
  • The response leaves out billing or payment_terms.
  • The Agent refuses the request with a code of its own, such as UNSUPPORTED_ACCOUNT_FIELD, or with a generic code, and does not name payment_terms.
Next step. For each agent-billed account we request terms for, either accept the requested payment_terms or reject the account. Never return it active on other terms. If your Agent cannot take the requested terms, reject the account with PAYMENT_TERMS_NOT_SUPPORTED and name payment_terms in the error. Return billing and payment_terms on every such account in sync_accounts and list_accounts.

Account sync is idempotent finding

Threshold. Per Source: a repeat sync_accounts that creates a second account for the same brand domain, operator and sandbox flag, or a list_accounts roster that lists one key more than once, is a flag. It is a blocker when this appears on three or more separate days in the seven days. Usual causes.
  • The Agent keys accounts on a generated id, or on brand alone, instead of brand domain, operator and sandbox flag.
  • A retry after a timeout runs the create again.
  • The sandbox flag is left out of the key, so a sandbox account and a live account collide, or the reverse.
Next step. Look up the account by brand domain, operator and sandbox flag before creating it. When it exists, return it with action: unchanged or updated and the same account_id. Merge the duplicates you already hold. Once each key is listed once, the finding clears as the seven-day window moves on.

Idempotent retries replay finding

AdCP binds an idempotency_key to the request it first arrived with. While the key is inside the seller’s replay window, the same key with an equivalent request returns the answer your agent already gave, and IDEMPOTENCY_CONFLICT is for a key that arrives with a different request. Apostra sends a request again under the same key when a call times out or a reply is lost, because it cannot tell whether the first send took effect. A refused retry leaves the buyer unable to read what happened to the first one. What we count. For each Source, over seven days, we look for requests we sent again: a request whose idempotency_key we had already sent, with the same body as that earlier send (we compare a hash of the body we recorded). This covers every call that carries a key, such as create_media_buy, update_media_buy, sync_accounts and sync_creatives. We judge a retry when your agent answered the earlier send with anything but IDEMPOTENCY_CONFLICT, and answered the retry. A retry your agent answers with IDEMPOTENCY_CONFLICT is a miss. We look for the earlier send in the seven days before the retry, because AdCP lets a seller declare a replay window of at most seven days (replay_ttl_seconds). We leave out a retry when either send asked your agent for a callback, because each send that does carries its own callback address and your agent sees a different request than the first one, so a conflict there is correct. We also leave out a retry whose earlier send was never answered, or was itself refused with IDEMPOTENCY_CONFLICT: your agent had no stored answer to replay. Threshold. One or more such retries in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source with judged retries and none refused passes. A Source we sent no request to twice in the window is not judged. What the finding shows. How many retries we judged, and how many your agent answered with IDEMPOTENCY_CONFLICT. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent compares requests with a fingerprint that changed when it upgraded its AdCP release, so a key stored before the upgrade no longer matches the same request.
  • The fingerprint includes something that differs on every send, such as a timestamp or a trace id the transport adds, instead of only what the request asks for.
  • The agent stores the key when a request arrives but the answer only when the work finishes, or in the memory of one instance, so a retry that lands on another instance, or after a restart or a deploy, finds a key with nothing to replay.
  • The agent keeps a key for less time than the replay_ttl_seconds it declares.
Next step. Store the answer with the key and the fingerprint of the request, in storage every instance reads and a deploy keeps, for as long as the replay_ttl_seconds you declare. When a request arrives with a key you hold and the same request, return the stored answer. Answer IDEMPOTENCY_CONFLICT only when the key arrives with a different request. Keep the fingerprint the same across an upgrade to a newer AdCP release, or carry the stored keys across when it has to change. The finding clears as the seven-day window moves on, after your agent replays the answer.

Reporting configuration echo finding

Threshold. For every sync_accounts request in the last seven days that carries reporting_delivery_configs, we compare each matching sync_accounts response and later list_accounts response with what we sent. An answer that omits, changes, or cannot validate a requested configuration is a flag. This is report-only today: it does not stop certification or buying. Usual causes.
  • A response mapper rebuilds a configuration and drops a required field, such as coverage_requirement.
  • The account store retains only part of the requested configuration, so list_accounts reports a different object than sync_accounts accepted.
Next step. Store the configuration you accepted without a lossy projection. Return every reporting_delivery_configs[].configuration exactly as requested from both sync_accounts and list_accounts, including coverage_requirement. Validate request and response objects with the pinned AdCP SDK schema rather than maintaining a parallel shape. The finding clears as the seven-day window moves on after matching live exchanges.

Reporting timezone matches declaration finding

A seller may report delivery in its own timezone. When a delivery response states reporting_period.timezone, it must be the same IANA timezone that the media buy’s products declare in reporting_capabilities.timezone. What we count. For each Source, over seven days, Apostra compares each reported delivery day with the declarations on every product in that media buy. A day is checked only when the response states a readable IANA timezone and every product declares the same readable IANA timezone. A response that states no timezone is not a finding. AdCP may omit it when packages report in different timezones, and an absent value means unknown, never UTC. A media buy whose product declarations are absent or disagree is not judged by this finding. Threshold. One or more delivery days that state a timezone different from the products’ declaration is a flag. This finding is report-only. It never changes which day Apostra books, holds back a buy or stops a certification pass from counting. A Source whose comparable delivery days all agree passes. A Source with no comparable day is not judged. What the finding shows. How many delivery days were compared and how many stated a different timezone. For the whole Agent, the counts add up across its Sources. Usual causes. The Agent reports UTC calendar days while its products declare the seller’s local timezone, or the catalogue declaration changed without the delivery report changing with it. Next step. Make reporting_period.timezone describe the calendar used for the reported days, and keep it equal to the timezone every product on the media buy declares in reporting_capabilities.timezone. If packages genuinely use different reporting timezones, omit reporting_period.timezone as AdCP specifies. The finding clears as the seven-day window moves on after the report and declarations agree.

Reporting window matches breakdown date finding

When a delivery response names a day in daily_breakdown[].date, its reporting_period.start and reporting_period.end must cover that calendar day in reporting_period.timezone. What we count. For each Source, over seven days, Apostra checks delivery days with an explicit date, a readable IANA reporting timezone and a positive reporting window no longer than 25 hours. The start and the last instant before the end must both fall on the explicit date in the stated timezone. A missing date or timezone is not judged. A window longer than 25 hours is not judged by this finding because one breakdown row does not prove how that window divides by day. Threshold. One or more comparable delivery days whose explicit date does not match the stated-timezone window is a flag. This finding is report-only. It never changes which day Apostra books, holds back a buy or stops a certification pass from counting. Apostra continues to trust an explicit date for booking when the window is positive and no longer than 25 hours. What the finding shows. How many delivery days were checked and how many named a date outside the reporting window in its stated timezone. For the whole Agent, the counts add up across its Sources. Usual causes. The Agent reports UTC-midnight windows while stating a local timezone, or uses a rolling 24-hour window instead of that timezone’s calendar day. Local calendar days can last 23 or 25 hours when daylight saving changes. Next step. Build reporting_period.start and reporting_period.end from the calendar named by reporting_period.timezone, including its daylight saving offset, and use that same local date in daily_breakdown[].date. The finding clears as the seven-day window moves on after matching reports arrive.

Declarations match behaviour finding

This finding compares two things your Agent declares with what it does when we call it. Billing. We count each sync_accounts request we sent in the seven days for a billing model you list in supported_billing. A request your Agent refused with BILLING_NOT_PERMITTED_FOR_AGENT or BILLING_NOT_SUPPORTED is a mismatch, whether the code came on the call itself or on the account in your answer. When we sent no request for a billing model you declare, billing is not judged. Operations. We read the tool list your Agent returns. For each of create_media_buy, update_media_buy, sync_creatives, sync_accounts and sync_audiences that you list, we look at every answer to our calls in the seven days. An operation is a mismatch when at least one answer refused it with UNSUPPORTED_FEATURE and none completed or was accepted for later completion. An operation that completed at least once is not a mismatch, even if another call was refused: you run it, and the refusal was about one feature of it. Answers such as CONFLICT, REQUOTE_REQUIRED and VALIDATION_ERROR say the operation ran and the request needed to change, so they never count. A sync_creatives refusal with UNSUPPORTED_FEATURE, the field assignments and the recovery correctable does not count either: Apostra sends the creatives again without the assignments, and the Creative assignments answered finding judges that answer instead. In the same way, a create_media_buy or update_media_buy refusal of one assignment item’s field that the Creative assignments on buys answered finding accepts does not count. That finding decides it against the request your agent was sent: UNSUPPORTED_FEATURE with a field that is the path of an item’s landing_page_url or trackers (for example packages[0].creative_assignments[1].trackers for trackers your agent does not take), of an item the request sent that carried more than a creative_id, and the recovery correctable or no recovery, which AdCP reads as correctable for this code. A refusal that finding counts as a miss, such as one marked terminal or one of an item that carried only creative_id, counts here too, and so does a refusal of an update that finding does not judge because your action list for the buy left out update_creative_assignments. The finding names the operation and the request field your error named, for example update_media_buy (3 refusal(s), naming push_notification_config). When we called none of the operations you list, operations are not judged. sync_audiences. One call can leave several records, so each call counts once, by its last answer: a refusal followed by a completed retry of the same call is not a mismatch. A call counts only when it completed, was accepted for later completion, or was refused with UNSUPPORTED_FEATURE. A timeout or any other error is left out, and the finding names no field. Every call we make to it is one your declaration says you take:
  • a read that lists the account’s audiences, which sends no audiences;
  • a bind of an audience from a partner source, sent only when you declare that source’s route in audience_targeting.supported_activation_methods; and
  • the delete of an audience such a bind created.
We never send your Agent members. So an Agent that lists audiences and refuses members, as List sync_audiences only where a buyer can use it advises, is not flagged. Only UNSUPPORTED_FEATURE is judged. An Agent that does not recognise the tool at all says so only in error text, such as “Tool not found”, which we do not match. Either mismatch is a flag. A mismatch seen on three or more separate days is a blocker. Today this finding shows on the Agent page and stops nothing. Usual causes.
  • supported_billing lists a billing model, such as agent, that your platform is not set up to accept for buyers.
  • The billing model is accepted only for some buyers or operators, but is declared for all.
  • Your tool list includes an operation your platform does not run, such as update_media_buy on a campaign model that cannot be changed after booking.
  • Your handler reads every request field as a change to make, so an optional field you do not use, such as push_notification_config or the version field on the request envelope, is refused. AdCP defines these fields as optional on the update request. A seller that does not send task webhooks ignores push_notification_config and lets the buyer poll tasks/get.
Next step. Accept every billing model you list in supported_billing, or remove the ones you refuse. Run every operation you list in your tools, or take it out of the list. Ignore optional request fields you do not use instead of refusing the call. If a change needs a new quote, such as an end date past the approved flight, answer REQUOTE_REQUIRED, which says the operation ran. A buyer chooses billing and plans corrections from your declarations, so one you declare and then refuse leaves an account unopened or a buy that cannot be corrected. Once your Agent stops refusing, the finding clears as the seven-day window moves on. See Keep capabilities current.

Buys judged on named products finding

Threshold. We read every create_media_buy we sent the Source in the seven days: the products each buy named in its packages, and your Agent’s answer. Either of these is a flag:
  • The same failure for every product. At least three buys, naming at least two different products, on at least two different days, failed with the same AdCP error code and message, and no buy succeeded in the seven days. The failure did not depend on the product the buy named. The finding names the error code. A refusal whose recovery is correctable does not count, because it tells the buyer what to change.
  • A product the buy did not name. Your Agent’s error named a product that the buy did not name: in details.product_id, in details.product_ids, or as a details value that is exactly the id of a product your Agent lists in get_products. The finding names the product. We match ids exactly and never read the error message.
Buys sent by a certification run are left out, and so is a buy whose request we cannot read back. This finding is never a blocker. Today it shows on the Agent page and stops nothing. Usual causes.
  • The Agent reads or validates its whole catalog on every create, so one product it cannot read, such as a pricing option with no rate, fails every buy.
  • The Agent cannot book at all, for example because its ad-server login expired or its account was disabled. Every buy then fails the same way too. The finding cannot tell this apart from the first cause, but your logs can.
Next step. Find the failed creates in your own logs and check whether the error came from a product the buy named. Then follow Decide each buy on the products it names. Once buys succeed again, the finding clears as the seven-day window moves on.

Valid responses finding

Apostra reads the replies your Agent sends to keep each buy’s status and delivery current. It reads a reply only when it is valid AdCP. A reply that fails the AdCP schema is refused whole, because reading part of it would risk showing a wrong status or wrong figures. This finding counts those refusals, so a reply Apostra cannot read no longer looks like a call that worked. What we count. For each Source, over seven days, every reply Apostra refused as not valid AdCP:
  • A get_media_buys reply. Apostra reads it to mirror the buy’s status and to check the buy against its contract. Each buy in the reply is checked against the AdCP media-buy schema.
  • A get_media_buy_delivery reply, where Apostra reads the Source’s delivery by polling. The reply as your Agent sent it is checked against the AdCP delivery schema.
A report your Agent pushes to the delivery webhook is not counted here. The Delivery report format finding judges it. To send reports and read what Apostra received, see Deliver reporting to Apostra. What does not count. Apostra applies its own corrections before it checks a reply, and only a reply that still fails afterwards is counted. A timestamp that carries a numeric UTC offset, such as 2026-09-01T00:00:00+00:00, is valid, and so is an optional top-level field of a delivery reply sent as null. A delivery payload Apostra built from a valid reply is not your reply, so a refusal of that payload is never counted against you. Threshold. One or more refused replies in the seven days is a flag. A reply is valid or it is not, and the same reply is refused the same way every time, so one refusal already names a field your Agent gets wrong. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source that sent no refused reply and was called in the window passes; a Source that was not called is not judged. What the finding shows. The count of refused get_media_buys and get_media_buy_delivery replies, and the fields that failed most often, each with its path and the Zod issue code, for example status with invalid_union. A path shows array positions as []. The finding never shows a value your Agent sent, only where the reply failed. For the whole Agent the counts add up across its Sources, and the fields are the most refused of all. Usual causes.
  • A timestamp that is not an AdCP date-time, for example one with no timezone or a date with no time.
  • A status that is not one of the AdCP media-buy statuses, or a field of the wrong type, such as a number where AdCP defines a string.
  • A required field left out of a buy or of a delivery row, such as by_package.
Next step. Validate every get_media_buys and get_media_buy_delivery reply against the AdCP schema for the release you declare before you send it, for example with the schema in the AdCP SDK. Fix the fields the finding names. Until a reply is valid, Apostra cannot show the status or the delivery of the buys it describes. The finding clears as the seven-day window moves on, after your Agent sends valid replies.

Account auth declaration finding

An Agent that declares account.require_operator_auth: false must accept account calls on the credential its Source connects with. This finding reports HTTP 401 refusals of those calls. What we count. For each Source that declares require_operator_auth: false, Apostra counts list_accounts and sync_accounts calls with an HTTP response in the last seven days, and how many returned HTTP 401. What does not count. Calls without an HTTP response, other tools, validation tests, manual replays and replayed requests. Sources that do not declare require_operator_auth: false, or whose capabilities have not been read and are inferred from the tool list, are not judged. Threshold. This finding is report-only. It is never a blocker and stops nothing. One or more HTTP 401 responses flags the Source; a Source with at least one judged call and no 401 passes. A Source with no judged calls is not judged. What the finding shows. The number of account calls refused with HTTP 401 and the number judged. The Agent adds those counts across its Sources. Usual causes. The agent may reject the configured connection credential, require a credential the Source does not have, or return HTTP 401 in error. Next step. Accept list_accounts and sync_accounts on the credential your Source connects with, as require_operator_auth: false declares. If your agent needs a credential, save it on the Source.

Tool list page size finding

AdCP’s Discovery responses stay small rule asks agents to keep each tools/list page under 128 KiB. Your tool list is the first thing a buyer’s agent reads. A large page costs every language model that loads it, and fails any client whose reply limit is smaller than the page. What we count. Apostra reads a third-party agent’s tool list when it refreshes capabilities, about once an hour, and a managed agent’s list at most once a day after a successful read. For each Source, we record the size of the page we read: each tool’s name, description and inputSchema, as JSON. What does not count. Other fields of each tool, and any page after the first. Apostra’s client reads only the first page today. Threshold. This finding is report-only. It is never a blocker and stops nothing. A page of 131,072 bytes (128 KiB) or less passes; a larger one is flagged. A Source whose tool list size Apostra hasn’t recorded yet is not judged. What the finding shows. The size we recorded. It is a lower bound: your page was at least that many bytes. On your Agent, the finding shows the largest size across its Sources. Usual causes. Tool lists can grow when they register unsupported tools, include response schemas or the whole AdCP schema catalog in each inputSchema, or use long descriptions. Next step. Shrink the list first: register only the tools you support, keep each inputSchema self-contained without response schemas or the whole AdCP schema catalog, and keep descriptions short. Paginate with nextCursor once Apostra’s client follows it. Today it reads only the first page, so tools on later pages would be lost (client issue). Apostra’s connect-by-URL read refuses any reply over 1 MB, so connecting by URL fails above that limit.

Wholesale catalog published finding

A sales agent that you connect to a Storefront as an inventory Source must publish its products for wholesale reading: it declares wholesale in media_buy.buying_modes, and answers get_products with buying_mode: "wholesale" with its products, avails and forecasts. The Storefront builds its own catalog from that read, and that catalog is what Chef composes proposals over and what a seller’s own proposal agent is checked against. An agent that only takes briefs (buying_modes: ["brief"]) is not an inventory agent. It plays the storefront role: it answers briefs itself and books for itself, and there is no catalog for another Storefront to build from. What we read. Two things, for each Source, from state Apostra already keeps. The first is the media_buy.buying_modes your agent returned the last time Apostra read your capabilities, about once an hour. The second is the result of our catalogue check: whether the wholesale read it makes without an account was answered with cache_scope: "account". Threshold. This finding is report-only. It is never a blocker and stops nothing: no certification result and no buy changes because of it. It is flagged when your agent does not list wholesale, or when it answered our account-less wholesale read with cache_scope: "account". It passes when your agent lists wholesale and our account-less read was answered as public. A Source that has no recorded buying modes is not judged on the declaration, but an account-scoped answer is still flagged. On your Agent, the finding is flagged when any Source is. Why an account-less read must answer public. AdCP requires cache_scope: "public" when the request names no account, because a public answer can be cached and served to every buyer. An agent whose forecasts depend on the caller’s own bookings can still publish a wholesale catalog: answer the account-less read with products and prices as public, and answer a read that names an account with the account-scoped forecasts and cache_scope: "account". While an account-less read is answered as account-scoped, Apostra cannot cache your catalog for the Storefront, and the Storefront can use it only through the catalogs it reads for its own buyer accounts. Usual causes. An agent built to answer briefs only, with buying_modes set to ["brief"]. An agent that serves a wholesale catalog but has not added wholesale to its declaration. An agent that scopes every wholesale answer to the caller’s account, with no account-less answer. Next step. List wholesale in media_buy.buying_modes and serve get_products with buying_mode: "wholesale", with avails and forecasts. If your forecasts are per account, leave them off the account-less answer and return them on the account-scoped one. If your agent only takes briefs, it plays the storefront role, and the finding stays flagged until it publishes a catalog. The declaration clears at the next hourly read of your capabilities. The account-scoped finding clears at the next catalogue check that reads a public answer.

Unscoped media buy list read finding

Once a day Apostra reads every media buy a Source holds for Apostra’s credential, to check that each buy Apostra booked is still one you hold and to find buys whose booking Apostra lost track of. It sends one get_media_buys request that names no media_buy_ids and no account, asks for all seven statuses in status_filter, and pages with pagination. AdCP makes both fields optional: with no account, your Agent returns buys across every account the caller may access, and with no media_buy_ids, it returns a paged set of those buys matching status_filter. This finding counts the reads your Agent failed. What we count. For each Source, over seven days, every such read that stopped on a page your Agent failed:
  • the task ended failed, for example because your Agent refused the request or failed its own check of the reply;
  • the reply carried an errors array;
  • the reply left out media_buys, held a buy with no media_buy_id or status, listed one buy twice, sent pagination that is not an object with a boolean has_more, or sent a cursor that did not move on.
A read your Agent answered in full, every page, passes. What does not count. A read Apostra stopped itself: at its own deadline (five minutes for the whole read) or a page limit, or a request that never got an answer, which the Reachability finding judges. A read your Agent refused for Apostra’s credential is not counted either. A page your Agent answers submitted is polled every ten seconds until it completes. A page still submitted or working, or paused as input-required, auth-required or deferred, when Apostra stops is not judged, because Apostra cannot poll it further. Threshold. One or more failed reads in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source whose reads were all answered passes; a Source Apostra did not read in the window is not judged. What the finding shows. How many reads were judged and how many your Agent failed, and the most common failure: your Agent’s own error code, such as VALIDATION_ERROR, or, when it gave none, what Apostra found wrong with the reply, such as pager_malformed_media_buy. For the whole Agent the counts add up across its Sources. The failure named is the one behind the most failed reads, with each Source’s failed reads counted under that Source’s most common failure. Usual causes.
  • Your Agent checks its own reply against the AdCP schema and fails the task, because a buy holds null in a field AdCP types as an object or a list, such as targeting_overlay.frequency_cap or geo_countries_exclude. Leave out a field that has no value.
  • Your Agent needs an account to list buys and refuses the request without one, although its capabilities do not say an account is needed.
  • Your Agent verifies request signatures and refuses a fresh request as a replay when two requests arrive within the same second. A replay check should refuse only a nonce it has already seen.
  • An internal error in your Agent while it lists buys.
Next step. Answer a get_media_buys request that names no ids and no account with every buy the caller may see, paged with pagination.cursor, in a reply that passes the AdCP schema for the release you declare. If your Agent needs an account on every request, say so in the account section of get_adcp_capabilities, and refuse a request without one with a correctable error that names the account field. The finding clears as the seven-day window moves on, after your Agent answers the read.

Daily budget on a lifetime buy finding

The budget Apostra sends on a buy is a total for the whole flight: a package’s budget and a buy’s total_budget are lifetime amounts in AdCP. A sales agent that places one in its ad server as a daily budget lets the buy spend its whole budget every day. This finding counts the buys where that happened. What we count. Apostra checks each buy it reads back against the terms the buy was booked on (see the agreed terms check). For each Source, over seven days, a buy counts when one of its packages, or the buy itself, held a daily budget the booking did not carry: a daily_budget_cap, or an averaged daily budget reported as ext.scope3.daily_budget_target. A daily budget the buyer did book is compared with the amount booked instead, and does not count here. An averaged daily budget held beside the booked total does not count either: when the package’s budget, or the buy’s total_budget, equals the amount booked, the total is held and the daily amount only paces it over the flight. A daily_budget_cap the buyer did not book always counts, because it limits spend the booking did not limit. Threshold. One or more such buys in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source with buys checked against their booking and none holding such a daily budget passes; a Source with no buy checked in the window is not judged. What the finding shows. How many buys were checked against their booking, and how many held a daily budget the booking did not carry. For the whole Agent the counts add up across its Sources. Usual causes.
  • The Agent creates the line item, ad set or campaign with a daily budget and puts the buy’s total into it, so the buy can spend its total every day.
  • The Agent reports an ad server’s daily budget as the package budget or the buy’s total_budget, so a daily amount reads as the total.
  • A budget changed to daily in the ad server after the buy was placed.
Next step. Place a package budget in your ad server as a lifetime budget for the flight, and report it back as budget, and the buy’s total as total_budget. If your ad server holds a daily budget the buyer did not ask for, report it as daily_budget_cap (a hard daily ceiling) or as ext.scope3.daily_budget_target (a daily budget your platform spends as an average), never as budget or total_budget. If your ad server paces a total with a daily budget, hold the total as a hard cap for the flight, report it as budget or total_budget, and report the daily amount as ext.scope3.daily_budget_target. The finding clears as the seven-day window moves on, after the buy holds its total again.

Property delivery finding

A product can declare that it reports delivery by publisher property: AdCP’s reporting_capabilities.supports_property_breakdown. When every product on a buy declares it, Apostra asks for the rows. Its get_media_buy_delivery read carries reporting_dimensions.property, with a limit of 250 rows per package (AdCP’s default is 25, which a display buy across many sites would exceed on its first day). This finding counts the packages where your agent declared the breakdown, was asked, and did not answer it. What we count. For each Source, over seven days, we read the get_media_buy_delivery calls we made that asked for property, and your agent’s answer to each. A package is judged on its latest answer in the window, so an agent that fixes its replies stops being counted. AdCP requires the answer to carry, for every package in by_package:
  • by_property, a list of rows, empty when nothing delivered;
  • by_property_truncated and by_property_suppressed, both booleans. They say whether rows were cut for the limit, or left out for a privacy, policy or measurement threshold, so a short list is never read as a complete one;
  • on each row, the property it names: publisher_domain and an identifier with a type and a value, plus spend and whatever other metrics you report.
A package counts as a miss when by_property is missing or is not a list, and as incomplete when the list is there but a flag is not a boolean or a row lacks one of those fields. An answer that carried errors, or whose stored body has been pruned, is not evidence either way. Threshold. One or more such packages in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source with packages asked for property rows and none missing passes. A Source we never asked, because none of its products declares the breakdown or no buy ran on it, is not judged. What the finding shows. How many packages we asked, how many came back without a by_property list, and how many came back with rows or flags that are incomplete. For the whole Agent the counts add up across its Sources. Usual causes.
  • Your products declare supports_property_breakdown: true but the agent only reports by_package totals.
  • The agent returns by_property only for packages that delivered, and leaves it out of the others.
  • The rows name the ad server’s own ad unit or site id but not the publisher_domain and identifier AdCP asks for.
  • The agent returns by_property without the by_property_truncated or by_property_suppressed flags.
Next step. If your agent can report delivery by property, return by_property on every package in by_package whenever the request carries reporting_dimensions.property, with both flags and complete rows. Honour the limit and say when you cut the list with by_property_truncated: true. If it cannot, remove supports_property_breakdown from your products’ reporting_capabilities, and Apostra stops asking. The finding clears as the seven-day window moves on, after your agent answers the request.

Audience expansion finding

A platform can deliver a buy beyond the audience the buyer stated: Meta’s Advantage+ audience, LinkedIn’s audience expansion, Pinterest’s auto-targeting. The AdCP audience expansion proposal (adcontextprotocol/adcp#9094) says a seller must not expand a package created through AdCP unless the buyer asked for it, and must report the setting on readback. Delivery beyond the buyer’s audience spends their budget on people they did not choose, so Apostra creates buys with expansion off and expects the same of your agent. This finding counts the buys where your agent reports expansion on and no request of ours asked for it. What we count. For each Source, over seven days, we read the buys as your agent reported them through get_media_buys. A buy is judged when a package reports audience_expansion.enabled, on or off, on its targeting_overlay (the proposal’s shape). Until AdCP ships the field, Apostra’s own adapters report the same object under ext.apostra.audience_expansion, and we read that too. A buy counts as a flag when a package reports enabled: true and no create_media_buy or update_media_buy request we sent, at or before that read, carried targeting_overlay.audience_expansion.enabled: true for that package (an update names its package by package_id, a create by product_id). A package that reports neither id cannot be matched to a request and counts. A request for one package does not excuse another, and a request sent later does not excuse an earlier read. AdCP has no way to ask yet, so today every buy that reports expansion on counts. A buy whose product expands by design counts too, for now. Threshold. One or more such buys in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source whose buys report expansion off passes. A Source that reports nothing is not judged. What the finding shows. How many buys reported the setting, and how many reported it on without being asked. For the whole Agent the counts add up across its Sources. Usual causes.
  • The platform’s default is automatic or expanded targeting, and your agent creates buys without turning it off.
  • A product expands delivery by design and nothing tells the buyer.
  • The setting is on in your ad server because the buy was created there before Apostra placed it.
Next step. Create buys with expansion off unless the buyer asked for it, and report the setting on every package, on or off, as audience_expansion on targeting_overlay. If a product expands by design, say so in the product’s description. The finding clears as the seven-day window moves on, after your agent reports the buys with expansion off.

Machine-readable errors finding

Threshold. Over seven days, any error we receive without a recognised AdCP error code is a flag. This finding is never a blocker on its own. Timeouts do not count here. Usual causes.
  • The Agent returns plain text, an HTTP status or a stack trace in place of an AdCP error.
  • The Agent returns its error entries as a bare array, for example [{"code": "VALIDATION_ERROR", "message": "..."}], instead of inside an AdCP errors array or an adcp_error envelope. The finding names this cause on its own: the entries carry a code, but not in a shape AdCP defines.
  • The Agent passes through the upstream ad server’s error, or uses its own code that AdCP does not define.
Next step. Map every failure path to the nearest AdCP error code and return it with a message, inside an errors array (or an adcp_error envelope) in the response. Start with the errors that appear most in your logs.

Creative error recovery finding

An AdCP error carries a recovery that tells the buyer what to do next: transient (send the request again later), correctable (change the request and send it again) or terminal (a person has to act). It is how a buyer’s agent acts on an error without knowing your error codes. When an error has none and the buyer does not know the code, AdCP has the buyer treat it as transient, so it retries a refusal that no retry will clear. What we count. For each Source, over seven days, we read each answer your agent gave to a sync_creatives call, as your agent sent it. The errors we read are every one in errors, the adcp_error when errors is not an array, and the errors of each creative in creatives. We do not read the error as the AdCP client library presents it, because the library fills in a recovery for an error that has none. Only an error that is a JSON object counts, so an error sent as a bare string is not judged. We check an answer when it carries at least one error. An answer is a miss when
  • an error has a recovery that is not transient, correctable or terminal, whatever AdCP release the answer was served at; or
  • the answer was served as AdCP 3.2 or later and an error has no recovery.
AdCP requires recovery on every error from 3.2: a 3.2 producer must populate it. For 3.1 it says a producer should, and a 3.0 error may leave it out. We read the release from the answer itself, from the front of its version, so 3.2, 3.2.1 and 3.3-beta.5 all count as 3.2 or later. An answer served as 3.1 or earlier, or one that does not say which release it was served at, with an error that has no recovery is not a miss. We still count it and show it as evidence, and it never flags. Where the Source is a storefront Apostra runs, a linked storefront or a leg of the wholesale pool, we count only the answers from 11 November 2026 14:59 UTC. Apostra’s own storefronts began to put a recovery on every failure then. Threshold. One or more answers that are a miss in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source with checked answers and none that are a miss passes. A Source that gave no creative sync answer with an error in the window is not judged. What the finding shows. How many answers carried an error, how many carried a recovery that is not one of the three, and how many answers served as AdCP 3.2 or later carried an error with no recovery. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent builds its errors by hand and leaves out recovery. The field is optional in the 3.0 schema it started from, and it moved to 3.2 or later without adding it.
  • The agent puts something else in recovery: a value of its own such as retry or fatal, a boolean for whether to retry, or null for no recovery.
  • The agent passes on an error from its ad server or another upstream service, with that service’s own fields and no recovery.
  • The agent adds recovery to the error at the top of the answer but not to the errors of each creative.
Next step. Put recovery on every error in a sync_creatives answer, in errors, in adcp_error and in the errors of each creative. Use transient when sending the same request again later can succeed, correctable when the request has to change, and terminal when a person has to act. Set it in your own error, not only through a client library that fills one in. The finding clears as the seven-day window moves on, after your agent’s errors carry it.

Creative review verdict finding

Your agent can answer sync_creatives at once with a creative in pending_review and no task for Apostra to poll. The buyer then learns your verdict only if your agent gives it another way: a callback to the push_notification_config the sync carried, or an answer to list_creatives. See Let us read your creative review verdict. When neither shows a verdict, the delivery waits and then fails, and the creative never reaches the buy. It waits seven days when list_creatives lists the creative in review, and until the delivery’s 30-minute deadline when it does not list it. What we count. For each Source, over seven days, we look at the creatives sent to it two ways: those a storefront delivered after approving them in its own review, and those a buyer synced straight to a storefront that passed them on to it. We judge a delivery when your agent answered its sync as completed with the creative in pending_review, and the sync carried a push_notification_config. A judged delivery is a miss when Apostra stopped waiting with no verdict: no callback came, and list_creatives did not show one when Apostra read the creative. For a creative a storefront delivered, Apostra stops waiting seven days after its first attempt when list_creatives listed the creative in review, and at the delivery’s 30-minute deadline when it never listed it. For one a buyer synced straight to a storefront, Apostra stops seven days after your agent’s answer. It passes when a verdict came first, from a callback or from a read. We count a stop against your agent only after Apostra read the creative with list_creatives and found no verdict. Apostra skips that read in some cases, for example when the sync’s account came from the route rather than from your agent, and a delivery whose verdict we never asked for is not judged. We count deliveries answered from 11 November 2026 18:58 UTC, when Apostra began reading verdicts this way. Threshold. One or more deliveries that reached their deadline with no verdict in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source with judged deliveries and none without a verdict passes. A Source with no delivery taken into review without a task in the window is not judged. What the finding shows. How many deliveries your agent took into review without a task, and how many of those reached the deadline with no verdict. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent does not implement list_creatives, or answers it without the creative’s status.
  • The agent lists creatives only in its default account, not the account the sync named, so the creative is not found.
  • The agent takes the push_notification_config on the sync but never calls it when the review finishes.
  • The agent’s review takes longer than the delivery’s deadline and it reports nothing in the meantime.
Next step. Answer list_creatives for a creative Apostra names, in the account the sync used, with its status and, when you assign it, its assignments. If your agent takes the push_notification_config on the sync, also call it when the review finishes. The finding clears as the seven-day window moves on, after your agent’s verdicts reach Apostra.

Delivery by creative finding

A delivery report can carry a by_creative list in each package, so a buyer can see which creative to keep. The list is only worth reading when each row is what your platform counted for that creative, and when the rows add up to the package. See Report each creative’s own delivery and What we need from reporting. What we count. For each Source, over seven days, we read the delivery reports Apostra received or read from it. We judge a package when it carries a non-empty by_creative and its impressions or its spend can be compared: the package and every creative row report that figure as a number. A package whose rows carry nothing we can compare is not judged, so it never reads as a pass. We judge each such package two ways:
  • Divided. The package has two or more creative rows and at least 1,000 impressions, and each of impressions, spend and clicks that the package and every creative row report is the package’s figure divided by the number of rows, within rounding (one for a count, one cent for money). Impressions and at least one other figure must be compared.
  • Does not add up. The rows’ impressions, or their spend, differ from the package’s own by more than rounding (one per row for a count, one cent per row for money) and by more than half a percent of the package’s figure. The half percent lets a creative read taken a moment after the package read pass.
Threshold. One or more packages that are divided or do not add up in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source whose creative rows are each their own and add up passes. A Source whose reports carried no creative rows in the window is not judged. Apostra’s own reads of your agent do not ask for creative rows yet, so a Source we read by polling is judged only when it sends them anyway. What the finding shows. How many reports and packages we judged, how many packages were divided, how many did not add up, and, for a Source, the first media buy and package. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent fills by_creative by splitting each package’s total evenly among its creatives, because its platform reports only by package.
  • The agent reports creative rows from a different query than the package row, at a different moment or with a different filter, so the two do not match.
  • The agent leaves out creatives that did not deliver in the report period, or one for which it has no mapping, so the rows total less than the package.
  • The agent reports delivery it cannot attribute to a creative in the package row but not in any creative row.
Next step. Give every by_creative row what your platform counted for the ads that ran that creative, never the package total divided by the number of creatives. Make the rows add up to the package’s impressions and spend: delivery you cannot attribute to a creative goes in an explicit row of its own. If your platform cannot report delivery by creative, leave by_creative out. The finding clears as the seven-day window moves on, after your agent sends corrected reports. How we measure it. We read the body of each delivery report Apostra received or read from your agent in the window, and compare each package’s creative rows with the package. The finding is Delivery by creative. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Delivery names only booked packages finding

When Apostra reads a buy’s delivery from your agent, it matches each reported package to the buyer’s package through the package_id your agent returned for that package when the buy was booked. A package row with an id the buy never booked cannot be matched, so Apostra drops it, and the buyer sees the buy’s totals without that package. What we count. For each Source, over seven days, we read the delivery reports Apostra received or read from it. We judge a report when its buy delivered something (impressions or spend above zero): a buy that has delivered nothing yet says nothing about whether your agent names its packages correctly, so it is never judged. A judged report is flagged when it names a package the buy never booked. We only count a package as never booked when the buy’s list of packages is complete on our side: a buy whose package list we could not record in full is our gap, and is never counted against your agent. Threshold. One or more flagged reports in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source that names only booked packages passes. A Source with no delivery to judge in the window is not judged. What the finding shows. How many reports we judged and how many were flagged, and, for a Source, the first media buy and package id. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent reports a platform’s own id for a package (an ad set or line item id) in delivery, and a different id in the create_media_buy response.
  • The agent regenerates package ids between create_media_buy and get_media_buy_delivery, for example by deriving them from the media buy id.
  • The agent reports delivery for a package that was added or removed outside the buy, such as an ad group created directly on its platform.
Next step. In each delivery report, give every by_package row the package_id your agent returned for that package in the create_media_buy response, and do not report a package id the buy never booked. The finding clears as the seven-day window moves on, after your agent sends corrected reports. How we measure it. We read the delivery reports Apostra received or read from your agent in the window, and the package ids Apostra kept from them that the buy never booked. The finding is Delivery names only booked packages. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Discovery brief accepted finding

Apostra discovers every Source with a no-spend get_products brief, and a buyer’s discovery read looks the same. If your agent answers a request that is valid AdCP with an error, no buyer can ever get your products: nothing they send would be valid to you. What we count. For each Source, over seven days, we read the get_products requests Apostra sent it, newest first (up to 500). We judge a request when it carries no account and passes the AdCP get-products-request.json schema of the version we speak (AdCP 3.3.0-beta.5 today), using only fields that schema defines, and your agent answered it with a completed read, a task status of input-required, or a failed call. It is refused when it failed with INVALID_REQUEST or VALIDATION_ERROR, the AdCP codes for a request that is not valid (enums/error-code.json). We do not count a timeout, an authentication, account, rate-limit or availability error, a request that was never sent, or a structured rejected answer. We judge the request’s shape and the answer’s task status and error code. We never match your error message. Which Sources. An active Source, and a pending Source of your own organization whether its health is failing or not. Refusing a valid brief is what makes a Source’s health fail, so this finding cannot wait for health that is not failing. On a pending Source whose health is failing, it is the only finding judged. Threshold. Two or more refused requests, and none answered, in the seven days is a flag. This finding is report-only. It is never a blocker, so it stops nothing: no buy is held back and no certification pass stops counting. A Source that answers its valid requests passes, and so does one that answers some of them (the call success rate finding judges that). A Source with no such request in the window is not judged. What the finding shows. How many requests we judged, how many were answered and how many refused, and, for a Source, the error code and your own message, quoted as text you wrote. For the whole Agent the counts add up across its Sources. Usual causes.
  • The agent requires a field in the brief that AdCP does not define, such as a KPI list, and refuses the brief with VALIDATION_ERROR until the buyer supplies it. Buyers cannot send a field they have no schema for.
  • A business rule, such as a minimum budget or a category your agent will not sell, is returned as VALIDATION_ERROR or INVALID_REQUEST when AdCP gives it a structured answer.
  • The agent validates the brief against its own, stricter schema than the AdCP version it declares.
Next step. Answer a brief that passes the AdCP request schema in one of the three ways AdCP defines, in the schemas of the version you declare:
  • With products, which may be an empty list: get-products-response.json.
  • To ask the buyer for more, with task status input-required, a reason of CLARIFICATION_NEEDED or BUDGET_REQUIRED, and suggestions that name what to add: get-products-async-response-input-required.json.
  • To decline a brief you understood, with task status rejected, a reason and optional suggestions: get-products-rejected.json.
Keep INVALID_REQUEST and VALIDATION_ERROR for a request that is invalid, with error.field naming the field. The finding clears as the seven-day window moves on, after your agent answers. How we measure it. We read the get_products calls Apostra recorded for your agent in the window: the request we sent, the task status of the last answer, and the error code. The finding is Discovery brief accepted. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Practices behind the findings

Return and honour payment terms on agent-billed accounts

What it is. When we ask for an account with billing: "agent" and payment_terms (for example net_60), do one of two things: accept those terms, or reject the account. If you reject it because of the terms, refuse with PAYMENT_TERMS_NOT_SUPPORTED and name payment_terms in the error. AdCP defines that code for exactly this, and it keeps the buyer from guessing which field you refused. Never return the account as active on different terms. On every account in your sync_accounts and list_accounts responses for an account we requested this way, return billing and payment_terms so we can see what you hold. AdCP states that the seller “must either accept these terms or reject the account — terms are never silently remapped.” Why buyers care. The buyer’s organization chose its payment terms. An account on other terms means invoices that don’t match what they agreed. What Apostra does when an Agent doesn’t. We refuse a new account that comes back on other terms. It is not activated, and it is held for the buyer to review the seller’s terms. An existing account stays usable, and the buyer sees a warning that names both the requested terms and the terms your Agent kept. How we measure it. We compare the accounts in your sync_accounts and list_accounts responses over the last seven days with the terms we requested. Only an account we requested with agent billing and payment_terms in that window counts. An account we requested without terms is on your default terms, as AdCP says, and isn’t counted. An account we never requested in the window isn’t counted either, and a response from before our request doesn’t count against the account. We don’t assume what your default terms are. A request we sent with payment_terms that your Agent refused with an error code AdCP does not define, or with UNSUPPORTED_FEATURE, INVALID_REQUEST or VALIDATION_ERROR, is a flag, counted once per account over the seven days. Codes that speak to another cause, such as ACCOUNT_SUSPENDED, ACCOUNT_SETUP_REQUIRED or BILLING_NOT_SUPPORTED, are not counted. For a counted account, a missing billing or payment_terms is a flag, and an active account on different terms is a blocker when your Agent created it or activated it on those terms, and a flag when your Agent already held it. Your Agent already held it when its sync_accounts response reports action: unchanged, or action: updated after an earlier response held the account active. A response that reports action: created or no action counts as a new account. An account that was a blocker at any point in the seven days stays one. A counted account whose listing has no billing counts as missing billing. We count accounts, not responses: an account is identified by its brand domain, operator and sandbox flag (and its brand id and operator unit, when you return them), however often it appears in your responses. An account counts as missing a field only while its latest response in the window lacks it, so it stops counting once your next response is complete. From list_accounts we read only your most recent roster, which is every page of your latest complete listing, so an account that has dropped out of it isn’t counted. An account returned on different terms stays counted for the seven days. This check reports today and does not yet stop new buys.

Sync accounts idempotently

What it is. The account key is the brand domain, the operator and the sandbox flag. When we send sync_accounts for a key your Agent already holds, return that same account with action: unchanged (or updated, if something changed) and the same account_id. Create an account only the first time the key appears. list_accounts lists each key once. Why buyers care. A buyer syncs the same account again whenever their setup changes. If each call creates a new account, the buyer’s buys, approvals and invoices spread across accounts nobody asked for, and the seller cannot tell which one is current. How we measure it. Over the last seven days we look for two things: two or more sync_accounts responses that report action: created for one key under different account_id values, and a list_accounts response that holds more than one account for the same key and sandbox flag. We read a list_accounts roster as every page of one listing, joined by pagination.cursor, and use the latest listing whose last page returns has_more: false; a listing that stops early isn’t used. Seeing either is a flag. Seeing it on three or more days is a blocker. A sandbox account and a live account for the same domain are different keys. Once your Agent merges the duplicates and lists each key once, the roster signal clears. This check reports today and does not yet stop new buys.

An idempotency key replays its stored answer

What it is. When we send a request again under an idempotency_key you already hold, with the same request, return the answer you stored for it. IDEMPOTENCY_CONFLICT is only for the same key on a different request. This holds across a deploy and across your own upgrade to a newer AdCP release: a key stored before the upgrade still replays after it. Why buyers care. A buyer’s agent retries when a call times out or a reply is lost, because it cannot tell whether the first call took effect, and the key is how it finds out. A seller that refuses the identical retry leaves the buyer unable to tell whether the buy, the creative sync or the change happened. How we measure it. We compare each request we sent again under a key with the earlier send, and the answer to each. The finding is Idempotent retries replay. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Every error carries a recovery

What it is. Every error your agent returns carries a recovery, one of transient, correctable or terminal. Use transient when sending the same request again later can succeed (a rate limit, an outage, a timeout), correctable when the request has to change (an invalid field, a creative the format does not accept), and terminal when a person has to act (a suspended account, a payment that is required). AdCP requires it on every error from 3.2, recommends it in 3.1, and lets a 3.0 error leave it out. A value outside those three is wrong in every release. This holds for every call your agent answers; sync_creatives is where we measure it. Why buyers care. A buyer’s agent does not know your error codes. recovery is how it decides between sending the request again, changing it, and asking a person. Without it, AdCP has the buyer fall back on what it knows of the code, and on transient for a code it does not know, so it retries a refusal that no retry will clear. How we measure it. We read each sync_creatives answer as your agent sent it, and check the recovery on every error in it against the AdCP release the answer was served at. The finding is Creative error recovery. It is advisory: it shows as a flag, never a blocker, and stops nothing.

A refusal suggests only what your agent accepts

What it is. When your agent refuses a request and names an AdCP operation or field to send instead, it takes what it names. A refusal that says to swap a changed creative in with an assignment_operations replace is a promise that your sync_creatives takes assignment_operations. If your agent does not take it, leave it out of the refusal, or say the change cannot be made. What AdCP says. The sync_creatives request schema of AdCP 3.2 defines assignment_operations (assign, unassign and replace) and deprecates the older assignments list in its favour. AdCP lists no capability a seller can decline it with. It does not say in so many words that a sales agent must take it, so a refusal is reported and not required. The one thing that is wrong in every case is to refuse the operation while telling the buyer to send it. Why buyers care. A buyer follows what a refusal says. If the refusal marks the error correctable, the buyer sends the operation, is refused again, and has no way out. On a live creative, that leaves the creative unchanged and the buy serving what the buyer meant to replace. How we measure it. On a live certification run, Apostra sends one sync_creatives request that carries an assignment_operations replace, to an agent it calls at AdCP 3.2 or later, and records how your agent answered. If your agent refuses it and names assignment_operations as what to send instead, in that refusal or in an answer on recorded traffic in the last 14 days, the finding is certification.assignment_operations_advice. If it refuses and names nothing, the finding is certification.assignment_operations_supported. See Assignment operations finding. Both are advisory: they show as attention, never a blocker, and stop nothing. How to fix it. Take an assignment_operations replace on sync_creatives. If you cannot yet, change the refusal so it names only what you accept. The findings clear the next time a certification buy is judged.

Declare AdCP channels on every Product

What it is. Every Product declares the AdCP media channels it sells in channels, such as display, olv, ctv, or streaming_audio. A Product that sells different channels through different formats can instead declare applies_to_channels on each format option. A format type on its own, such as a video or audio format, is not a channel, because several channels share a format. Why buyers care. Buyers filter discovery, route proposal requests, and report delivery by channel. A Product with no channel is missing from channel-filtered discovery, and its delivery reports with no channel. How we measure it. We read channels, then applies_to_channels, on the Products returned by our get_products calls. Storefront readiness counts the Products that declare neither (storefront readiness reports it as the check Product channels declared), the agent read shows it as the advisory finding declaration.product_channels, and live-path certification skips such a Product with the reason missing_channels rather than certifying it on a guessed channel. When a Product relies on applies_to_channels and only some of its format options declare it, the other formats are skipped with the reason missing_channels:<format_kind>. This is a best practice: a missing channel produces a warning and never blocks your Agent or fails its certification. We do not refuse an external Agent’s Products for missing channels. AdCP is considering making channels required on every Product in AdCP 4.0 (adcontextprotocol/adcp#7869); if it does, AdCP compliance will require it.

Keep your two format lists in agreement

What it is. A Product can declare its creative formats twice: in format_options, the canonical list, and in format_ids, the legacy list kept for AdCP 3.x buyers. When it carries both, AdCP requires them to describe the same formats. Every format a format option names in v1_format_ref must also be listed in format_ids, and every entry of format_ids must be a format that some option names in v1_format_ref or matches. An option that sets canonical_formats_only: true names no v1_format_ref. A Product that publishes only format_options has nothing to keep in agreement. How a reference matches. A v1_format_ref and an entry of format_ids name the same format only when all of agent_url, id, width, height and duration_ms agree, as in the AdCP SDK. A field one side sets and the other leaves out counts as a difference. Matching on agent_url and id alone is not enough. For example, these two do not match, because only the format_ids entry carries a size:
Give both the same fields: add width and height to the v1_format_ref, or remove them from the format_ids entry. Why buyers care. AdCP treats lists that disagree as a seller bug (FORMAT_DECLARATION_DIVERGENT), because a buyer cannot tell which list to trust. The AdCP SDK refuses a whole get_products answer that carries one such Product. Apostra judges each entry on its own instead. It leaves out an option whose v1_format_ref has no matching entry in format_ids, under the match above, and a format_ids entry that no option covers. It then serves the Product with the entries that remain. A reference that differs only in width, height or duration_ms is one of these disagreements: the entry is readable, it just does not match. A Product whose lists still disagree is left out of buyers’ answers, and the answer carries an errors[] entry with the code FORMAT_DECLARATION_DIVERGENT that counts the Products left out and names up to 20 of them. A storefront that holds its sources to format compliance also adds an option for a legacy format no option covers, and leaves out a Product it still cannot read before the answer is built, recording it on the Source’s health instead. Your other Products are served as usual. How we measure it. We read format_ids and format_options on the Products returned by our get_products calls, and judge them with the same check that serving uses to leave a Product out. The agent read shows the result as the advisory finding declaration.product_format_declarations. It counts the Products whose lists disagree and how many of those buyers do not get, and it names up to three of them with the disagreement, for example interstitial_320x480 is named in a v1_format_ref but not in format_ids. The finding is advisory: it stops neither certification nor buying. Whether it becomes required is a later, announced decision. Next step. For each Product named:
  • When an option names a format in v1_format_ref that format_ids leaves out, first compare the two entries field by field: often the format is listed, but one side carries width, height or duration_ms and the other does not. Make them identical. Otherwise add that format to format_ids, or correct the reference if the option is a different format.
  • When format_ids lists a format that no option names or matches, add an option for it, or remove it from format_ids.
  • When an option sets canonical_formats_only: true, remove its v1_format_ref.
The finding clears the next time Apostra reads your Products.

Accept the creatives your formats declare

What it is. Each format option on your Products tells buyers what a creative for it must be: the sizes an image may take (for example main_image_sizes on a native_in_feed option), the length of a text slot (title_max_chars, body_text_max_chars, cta_max_chars), and the values a slot may hold (cta_values). A creative that fits those declarations must be accepted by sync_creatives. Declare only what your agent accepts, and accept everything you declare. A slot whose values you do not narrow takes free text: AdCP’s cta_values, when set, narrows the call to action to a closed list, so with none set any call to action fits. Why buyers care. A buyer builds its creative from your declaration. When your agent then refuses that creative, the buyer has no way to know what you will take, and the buy cannot go live. How we measure it. Certification builds its test creative to what the format option declares. That is either a creative the AdCP SDK finds fits the option exactly, or one built from the option’s slots with every image at a size the option declares and every text slot within its declared length and values. When your agent refuses such a creative as not fitting, the certification result says so and names what the creative was built to, for example main_image 600x400. The advisory finding certification.declared_formats_accepted counts it. The refusals counted are a final answer with one of AdCP’s codes for a creative that does not fit: CREATIVE_SIZE_MISMATCH, CREATIVE_VALUE_NOT_ALLOWED, CREATIVE_VALIDATION_FAILED_GENERIC, or VALIDATION_ERROR. A refusal of the creative’s content, such as CREATIVE_REJECTED or POLICY_VIOLATION, is not counted, because a seller may refuse a creative that fits its format on what it shows. A creative built at a size or length the option does not declare is not judged either, such as a video whose option declares a size but no length. The one exception is CREATIVE_VALUE_NOT_ALLOWED, which is about a text value, not a size: it is counted whenever every text value Apostra sent is one its slot allows (the slot declares no closed list, or the value is on it), even if an image was built at a size you do not declare. The finding reads the latest certification result for each format on each Source in the last 14 days, including a Source still pending certification, and leaves out a Source that is disabled. It is advisory: it stops neither certification nor buying. Whether it becomes required is a later, announced decision. Next step. For each refusal the finding names:
  • When your agent refused a size it declares, accept that size, or take it out of the declaration, for example out of main_image_sizes.
  • When it refused a value in a slot whose values you do not declare, accept free text there, or declare the values you take, for example in cta_values.
  • When it refused a length within the declared limit, accept it, or declare the limit you enforce, for example in title_max_chars.
The finding clears with the next certification result for that format.

Decide each buy on the products it names

What it is. A buy succeeds or fails on the products it names. One product your Agent cannot sell, for example one whose pricing is incomplete, must not stop buys of your other products. When a buy names a product you cannot sell, refuse it with AdCP’s PRODUCT_UNAVAILABLE, recovery correctable, and the product’s id in details.product_id. Never fail a buy over a product it did not name. Never drop a named product and book the rest of the buy, and never answer PRODUCT_NOT_FOUND for a product you list. Why buyers care. A buyer picks products from your get_products answer. If one broken product fails every buy, no buyer can buy anything from you, and the error does not say which product to avoid. PRODUCT_UNAVAILABLE naming the product tells the buyer to choose another, and your other products keep selling. How we measure it. The Buys judged on named products finding reads the creates we send your Agent. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Answer package assignments on a creative sync

What it is. A sync_creatives request can carry assignments, which assign the creatives to packages in the same call. Your agent either takes them, or refuses them with UNSUPPORTED_FEATURE, recovery correctable, and the field assignments. A refusal in that form tells the buyer to assign through update_media_buy packages[].creative_assignments instead. Why buyers care. A refusal of assignments that is not in that form looks like a failure of the whole sync, so the creatives never reach a package and the buy does not deliver them. With the correctable refusal, Apostra sends the creatives again without the assignments and assigns them itself. Your agent answered, so the correctable refusal never counts as a failing Source: your Source’s health shows it as degraded at most, and it does not stop the Source going live or selling. How we measure it. We read the creative syncs that carried assignments and how your agent answered each. The finding is Package assignments are answered as AdCP allows. It is advisory: it shows as a flag, never a blocker, and stops nothing. When one Source of a buy refuses a creative for its own packages while another Source took it, a refusal that sets field on each error, to assignments or to the package it names, is reported on the packages it refused, and the Sources that took the creative keep it. A refusal without field fails the whole sync.

Let us read your creative review verdict

What it is. Your agent can answer sync_creatives at once with a creative in pending_review and no task for us to poll. Apostra then learns your verdict by reading the creative with list_creatives, filtered to its creative_ids and scoped to the account the sync used. It reads a minute after the sync, then less often, up to every ten minutes, until the delivery’s deadline. It never sends the creative again to ask about it, so your agent does not see repeated syncs under the same idempotency key. A storefront can also pass a buyer’s creative straight to your agent, without a review of its own. Apostra reads that creative the same way, scoped to the account the storefront sent you, for seven days after your answer. If no verdict has come by then, it stops reading and the creative stays in review. Why buyers care. The creative reaches the buy only once Apostra sees your approval, and the buyer sees your rejection only once Apostra reads it. What it means for you. Answer list_creatives with the creative’s status and, when you assign it, its assignments. If your agent took the push_notification_config on the sync, also send the verdict there when the review finishes. An agent that does neither leaves the delivery waiting until its deadline, when it fails. How we measure it. We look at each delivery your agent took into review without a task, and whether its verdict reached Apostra before the deadline. The finding is Creative review verdict. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Answer creative assignments on a media buy

What it is. A package on create_media_buy or update_media_buy, in packages or in the packages an update adds in new_packages, can carry creative_assignments: the creatives that run on that package. Each item names a creative_id, and may also carry weight, rotation_mode, group_id, sequence_position, placement_refs, placement_ids, landing_page_url and trackers. Your agent takes the list, or refuses an item in one of the forms AdCP defines:
  • VALIDATION_ERROR, with a field that is the path of the item and the part of it you cannot honour, such as packages[0].creative_assignments[1].weight, for a weight, a rotation or a placement your platform cannot apply.
  • UNSUPPORTED_FEATURE, with a field that is the path of the item’s landing_page_url or trackers, such as packages[0].creative_assignments[1].trackers, when your agent does not declare creative.supports_assignment_landing_page or creative.supports_assignment_trackers.
Name one item and one of its AdCP fields, by their positions in the request, such as new_packages[0].creative_assignments[0].weight for an item of a package the update adds. A field for the whole list, such as packages[0].creative_assignments, does not say which item to change. Give either refusal the recovery correctable: the buyer can change or drop the field. An error that leaves recovery out is read as correctable, AdCP’s own recovery for both codes, but send it explicitly. The same refusal marked terminal or transient is not one AdCP defines. An item that carries only a creative_id asks for nothing your agent can decline, so never refuse it for the assignment itself. Never answer with another code, such as INVALID_REQUEST. AdCP’s codes about the creative or the buy stay the right answers when they apply: CREATIVE_NOT_FOUND for a creative your agent does not hold, for example, or INVALID_STATE for a buy that cannot change. If you do not take creative changes on a live buy, say so in the action list you return on get_media_buys by leaving out update_creative_assignments, and the sync_creatives action that covers it. Apostra then does not send the change. Why buyers care. A buyer pins each line item of a buy to the creatives that should run on it. A refusal in one of the forms above tells the buyer which item to change. Any other refusal looks like a failure of the whole buy, so the buyer cannot tell what to fix. How we measure it. We read the create and update requests that carried creative_assignments and how your agent answered each. The finding is Creative assignments on buys are answered as AdCP allows. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Return the buyer creative id in creative approvals

What it is. On get_media_buys, a package can list the review state of its creatives in creative_approvals. Each item’s creative_id is the buyer’s id for the creative: the creative_id on the buyer’s sync_creatives request or in its creative_assignments. AdCP marks the field as a creative id. Your agent’s own id for the creative is platform_id on the sync_creatives answer, and buyers never send it back. If your agent has an id of its own to report on an approval, put it in ext. Why buyers care. The buyer matches each approval to a creative it holds by creative_id. An id the buyer never sent matches nothing, so the creative shows no review result, and a rejection never reaches the buyer to be fixed. How we measure it. We compare the ids your agent lists in creative_approvals with the creative ids we sent it. The finding is Creative approvals use buyer ids. It is advisory: it shows as a flag, never a blocker, and stops nothing.

Creative ids with a tilde

What it is. When one creative serves several packages in a buy and your agent cannot fill our package id itself, Apostra can send your agent one copy of the creative per package. Each copy has its own creative_id: the buyer’s creative id, a ~, and the package’s id without its sf_pkg_ prefix, for example cr_1~mb_4YZ57AKTVK_2. Your agent must treat that id like any other:
  • store it exactly as sent, with no change of case, no escaping or encoding of the ~, and no cut in length. Keep ids of at least 128 characters;
  • echo it unchanged as the creative_id of its result in sync_creatives;
  • take it in a package’s creative_assignments in update_media_buy, and report the package as holding it in creative_approvals on get_media_buys;
  • list the creative under that id in list_creatives, and report its delivery under that id in the by_creative rows of get_media_buy_delivery;
  • use that id, unchanged, in every asynchronous sync_creatives callback and in any review verdict it reports for the copy, including creative_approvals on get_media_buys.
Do not split the id at the ~, and do not treat the part before it as the creative. Your agent’s own id for the creative is platform_id, and it must not replace creative_id anywhere. Why buyers care. Apostra rolls each copy back up to the buyer’s creative by its exact id. An id your agent changes or shortens matches no copy, so the creative’s review result and its delivery never reach the buyer, and a rejection cannot be fixed. A copy that is lost this way also shows no click or impression for its package. What Apostra does with a callback. A callback your agent sends for a copy reaches the same Apostra callback endpoint as any other sync_creatives callback. Apostra checks it against the AdCP sync_creatives response schema, which puts no pattern or length on creative_id, and then matches the id exactly against the copies it sent. It changes nothing about the id before that. A callback under an id that matches no copy we sent is treated as it would be for any creative id we do not know. How we measure it. Certification syncs your agent one creative under an id of this shape, 128 characters long, and reads it back with list_creatives. It then assigns the copy to a package of the same test buy, in an update_media_buy whose creative_assignments for that package keeps what the package already holds and adds the copy, and reads the buy back with get_media_buys. The creative is the one Apostra already sent your agent on its test buy, with only its id changed. Apostra sends the assignment only to a package of its own test buy that is booked under its sandbox account, which cannot spend; with no such package the check is not run and your agent is not judged. The finding is certification.creative_copy_id. It fails when your agent refuses the id, answers under another id or none, lists no creative under it, refuses the assignment, or accepts it and then reports the package as holding other creatives and not the copy. The last case is judged only when your agent’s creative_assignments_as_of for the package has moved on since the read taken before the update, because an absence means nothing from a set that has not been refreshed since. Apostra does not settle the check on the first read of an unrefreshed set: it sends the assignment once and reads the buy again on later passes for up to 24 hours. Once the set has moved, a package that holds the copy passes and one that does not fails. A set that never moves in those 24 hours leaves the check inconclusive, not failed, because AdCP sets no refresh cadence. The check can only pass once your agent reports the package as holding the copy in the creative_approvals of get_media_buys (the list that the creative_assignments in the update produces, and that creative_assignments_as_of dates), and a source’s copies are turned on only after it has passed. It does not exercise delivery reports or asynchronous callbacks under the id, so those are on you to keep exact. It is advisory: it shows as a flag, never a blocker, and stops nothing. Apostra sends copies to a source only after a member of staff turns that on for it, and does so only when this check has passed for the source. How to fix it. Find where your agent stores or normalises a creative id (a column with a length limit, a slug or lowercase step, a URL-decoding step, a split on ~), and keep the id as an opaque string. If your agent refuses the assignment, accept a wire id in a package’s creative_assignments the way you accept any creative id there. If it accepts it and does not report it, list the package’s creative under creative_approvals from the same store the assignment wrote to. The finding clears the next time a certification buy is judged.

Report each creative’s own delivery

What it is. In get_media_buy_delivery, each by_creative row in a package reports that creative’s own delivery: what your platform counted for the ads that ran it. Never fill the rows by dividing a package or campaign total among its creatives. If your platform cannot report delivery by creative, leave by_creative out. AdCP makes it optional, for sellers that support creative-level reporting. Why buyers care. Buyers and their agents compare creatives to decide which to keep, refresh or drop. Rows made by dividing a total make every creative in the package look the same, so that comparison tells them nothing, and nothing in the rows says the figures were divided. How we measure it. On live traffic, as a report-only finding: a package whose creative rows are equal shares of its total reads as a flag. See Delivery by creative finding. Apostra’s own adapters are also tested so that none of them divides a total among creatives. This is requirement WNR-3 on What we need from reporting, which lists the other rows and figures a buyer needs and says which are judged.

Accept the audiences you list as ready

What it is. When your agent answers a sync_audiences call that sends no audiences (discovery mode), every audience it lists on the account with status: "ready" is one a buyer can target on that account. Take it on create_media_buy and update_media_buy when a package’s targeting_overlay.audience_include or audience_exclude names it. AdCP says these fields reference “audience_id values from sync_audiences on the same seller account”. That covers an audience made on your platform before the buyer connected, not only the audiences your agent created from members a buyer sent. AdCP does not yet say which identifier a buy uses for an audience made on your platform: its audience_id, or its platform id (platform_id, which AdCP 3.3 also sends as seller_id). This is an open question for AdCP. Today Apostra sends the platform id your discovery answer reports for the audience, or its audience_id when you report no platform id. If your agent cannot target an audience it lists, do not list it as ready: report it as processing, too_small or suspended, or leave it out. An audience can shrink after it was listed. Refuse a buy on one that is now below your minimum with AUDIENCE_TOO_SMALL, and report it as too_small on the next sync. Why buyers care. A buyer maps an audience you list to one of its own, and Apostra checks that it is on the account and ready before the buy is sent. If your agent then refuses that id, the buy fails at launch after every check passed, and the refusal gives the buyer nothing to fix. How we measure it. Today Apostra checks this for its own ad platform connections, one platform at a time. It counts the buys that carried an audience proved ready on the account and were refused with INVALID_AUDIENCE_REFERENCE or AUDIENCE_NOT_TARGETABLE. The check is advisory and stops nothing. Third-party sales agents are not judged yet. Apostra proves a mapped audience on a seller account only through its own platform connections, so no buy to your agent carries an audience it has proved ready. Once it does, a behaviour finding judges your agent on the same rule. It starts as advisory. A related practice covers the promise itself: List sync_audiences only where a buyer can use it.

List sync_audiences only where a buyer can use it

What it is. sync_audiences does two jobs. Called with audiences, it creates an audience and adds and removes its members. Called without, it lists the audiences already on the account. Listing it in your tools tells a buyer at least one of these is worth doing on your agent. List it only when your agent does one of them:
  • it creates an audience from members a buyer sends, and adds and removes members; or
  • it lists audiences that a buyer can then target in a package’s targeting_overlay.audience_include and audience_exclude.
AdCP cannot yet say that your agent does only the second. Listing the tool, or declaring media_buy.audience_targeting, reads as “takes members” too. This is an open question for AdCP. Until it is settled, an agent that takes existing audiences but no members lists sync_audiences, and refuses a call that sends audiences with UNSUPPORTED_FEATURE. Why buyers care. A buyer plans an audience around your tool list. If your agent lists sync_audiences but takes no members and offers no audience targeting, the buyer builds and sends a customer list that is refused, or maps an audience it can never target. How we measure it. Apostra checks this for its own ad platform connections, one platform at a time.
  • Each platform lists sync_audiences only when its audience support takes members or backs audience targeting on a buy.
  • Its readiness report flags a platform that lists sync_audiences with no passing audience canary in the last 30 days.
For every other sales agent, the Declarations match behaviour finding flags an agent that lists sync_audiences and, over seven days, refused every call we made to it with UNSUPPORTED_FEATURE and completed none. We never send a third-party agent members, and we bind an audience from a partner source only when the agent declares that source’s route. So an agent that lists audiences and refuses members, as described above, is not flagged. Only UNSUPPORTED_FEATURE is judged: an agent that does not recognise the tool at all says so only in error text, which we do not match. Both checks are advisory and stop nothing. They are separate from Accept the audiences you list as ready, which judges a refusal of an audience your own listing showed as ready. How to fix it. If your agent takes neither members nor audience targeting, stop listing sync_audiences. If it takes members, keep it listed, and answer every call that sends audiences.

Echo the context we send

What it is. When our request carries a context, return it unchanged on your response: on a success, an error and an async submitted or working answer alike. On each package of a response, return the context our request sent with that package. On get_media_buys, return on each media buy the context our create_media_buy sent for it, and on each package the context that package was created with. This is AdCP’s rule for context. Today we send our own context on every create_media_buy (storefront_media_buy_id) and on each of its packages (storefront_package_id). Why buyers care. We use the echoed context to match your media buys and packages to ours, even when we have not yet recorded your ids. Without it a buy found on your side cannot be tied to the buyer’s buy, and its status and delivery can go unreported. How we measure it. We compare every response with the context we sent it, from our live calls. We compare JSON values, so key order does not matter and a number counts as the same value however it is written (1 and 1.0). No context back, or a different one, is a miss, and any miss is a failure: the source’s health shows a context_echo_missing finding that names the tools. The finding clears once your agent echoes the context again and a day passes with no miss. It does not stop buys or change certification. We do not judge a call to a tool your agent does not offer. If our call comes back as your server’s own answer that the tool was not found (for example MCP error -32602: Tool sync_creatives not found), that is no task response and has no context to echo, so it is never counted as a miss.

Keep one opportunity together

What it is. Our buyer agent sends an AdCP opportunity with the opportunity_id of the campaign the work is for, on request_proposals. A brief sent through get_products carries the same value as ext.adcp.opportunity. It is the same value on every brief for one campaign, opaque, and one to 255 characters from A-Z, a-z, 0-9, _, ., : and -. We never send a changed form of it. For a campaign whose ID does not fit, we send the brief without it. We do not send opportunity on create_media_buy: AdCP requires a proposal_id alongside it, and our creates name explicit packages. Why buyers care. AdCP scopes the ID to you and the buyer account, so you can hold a campaign’s briefs and proposals together, and the buyer sees them as one conversation with you. Treat the ID as a label to correlate on. It is not a proposal or media buy ID, and it has no meaning to parse.

Return the account on each media buy

What it is. On get_media_buys, return on each media buy the account it was placed under, with its account_id. AdCP makes account optional on a media buy, so leaving it out breaks no rule, but we use it to learn which of your accounts a buy belongs to. Why buyers care. Your change feed is keyed by account. When we know a buy’s account we can match the buy to the feed that announces its changes, so its status reaches the buyer when you announce it instead of when our next scheduled read finds it. A buy placed by brand and operator names no account when it is created, so get_media_buys is where we learn it. How we measure it. Each status read of a live buy that returns an account.account_id records it on our side. If your agent offers the change feed and a live buy still has no recorded account three hours after it was placed, the source’s health shows a route_account_unresolved finding with the count and the age of the oldest. The finding clears once your agent returns the account. It does not stop buys or change certification; the buys stay on scheduled reads.

Answer status reads for every buy

What it is. Answer get_adcp_capabilities at AdCP 3 and get_media_buys for every media buy you hold, whatever its state. Why buyers care. You own a buy’s state. If a buy shows completed on our side without you ever reporting it completed, only a successful status read tells us whether it is still running. If we cannot read your agent, a buy you are still delivering can read completed to the buyer. How we measure it. We poll each buy’s route. If a buy we hold as completed with no report from you sits behind a route we cannot read, for example an agent that does not advertise get_adcp_capabilities, the source’s health shows a completed_buys_unreadable finding with the count of buys and what the read failed with. We read a route we know your agent cannot answer once a day, not hourly. The finding clears once a read succeeds, and each buy then takes the status you report. It does not stop buys or change certification.

Report pending start until the flight starts

What it is. A buy that is booked, approved and enabled, but whose start_time has not come, is pending_start. AdCP’s lifecycle has no running state before a flight begins, so report pending_start in every read of that buy: get_media_buys, get_media_buy_delivery, and any webhook. When the flight starts, report active. A buy that is missing creatives is pending_creatives instead, as the lifecycle puts it first. This holds even when your ad platform shows the campaign as enabled or running. Why buyers care. A buyer or its agent that reads a buy before the flight sees the status your agent reports. When two of your reads name different statuses for the same buy, our record of the buy follows whichever read arrived last, so the buy changes state every few minutes until the flight starts. An alert that fires on a buy running before its flight, or on a paused buy, then fires on churn that is not real. How we measure it. We read the statuses your agent reports for each buy and count a buy whose status goes back and forth between the same two statuses. The finding is A buy keeps one status. It is advisory: it shows as a flag, never a blocker, and stops nothing. Separately, Lifecycle agreement compares get_media_buys with get_media_buy_delivery for the same buy and counts a disagreement that lasts more than 15 minutes.

Resolve the property lists we send

What it is. When a buyer’s property lists apply, we send your Agent a property-list reference: an agent_url, a list_id and an auth_token, in a discovery request or in a media buy’s targeting. Your Agent fetches the list from agent_url and keeps its Products and delivery inside it. We serve each list two ways, and both return the same list in the AdCP property-list shape.
  • AdCP get_property_list over MCP. This is how the AdCP SDKs resolve a reference, for example resolvePropertyList in @adcp/sdk/server. Call the get_property_list tool on the MCP server at agent_url, with the reference’s auth_token as the bearer credential. The list is in the tool result’s structuredContent. Send it as its own request: inside a JSON-RPC batch it is refused.
  • REST. GET {agent_url}/lists/{list_id} with Authorization: Bearer {auth_token}.
Credentials and errors. Each auth_token opens only its own list_id. With no credential, get_property_list returns AUTH_REQUIRED. A token that does not open the list returns REFERENCE_NOT_FOUND, exactly as a list that does not exist does, so the answer never reveals whether a list exists. An unreadable cursor returns INVALID_REQUEST. Pages and caching. Follow pagination.cursor while pagination.has_more is true. A page holds at most 5,000 identifiers: over MCP a larger pagination.max_results (AdCP allows up to 10,000) returns 5,000, and over REST it is rejected. Calls to get_property_list are limited to 600 a minute per caller. Cache each page until cache_valid_until. When a list’s contents change we send the same list_id again, so treat that as a signal to fetch it again. Why buyers care. A buyer’s property lists say where its ads may and may not run. An Agent that cannot read them cannot keep that promise. How we measure it. The Honours request finding covers Products returned outside the property list we sent.

Source reporting health

What it is. Every inventory source that uses your agent is expected to deliver its delivery reports on time. Apostra reads each source’s reporting state as one of five values: Why buyers care. Buyers reconcile spend and delivery from these reports. A report that does not arrive leaves the buy open. How we measure it. We count the states across the agent’s authorized inventory sources. The finding reporting.sources is an attention finding when any source is action_required, and passes when none is. Nothing stops: running buys continue. The inventory sources page shows each source’s own state. See Reliable Reporting for the capability that makes reports dependable, and Deliver reporting to Apostra for how to get reports to Apostra and read the receipts.

Take property-list changes on live buys

What it is. When a buyer’s property lists change while a buy is running, your Agent receives the change through update_media_buy, if it declares support for buyer property lists. A seller that does not declare it receives nothing for the change.
  • A new reference. When the buyer creates, archives or deletes a list, or applies or clears a campaign’s list, update_media_buy carries the reference now in effect on each package. Resolve its list_id and confirm the update.
  • New contents, same reference. When only a list’s contents change, the reference and its list_id stay the same, but update_media_buy is still sent. Treat it as a refresh signal: fetch the current list before using a cached copy again, instead of waiting for cache_valid_until.
Why buyers care. A buyer’s lists say where its ads may and may not run, and a change applies to buys already running. How we measure it. Before a buy launches, Apostra checks that something enforces every list on each of its products. After a change, a live buy whose seller rejects or does not confirm the update, or that nothing enforces any more, is paused and the buyer is told why; see When a live buy is paused.

Ask us to wait with Retry-After

What it is. When your Agent is over its request budget, answer HTTP 429 with a Retry-After header, given in seconds or as an HTTP date. A 503 with Retry-After is read the same way. Why buyers care. Scheduled work that keeps calling a rate-limited Agent spends the budget your buyers’ own requests need. How we use it. We record the time you name against your Agent’s endpoint. Until then, none of Apostra’s scheduled work calls the Agent: catalog refreshes, capability checks, status polls and change-feed retries all skip it. The wait covers every storefront that uses the same endpoint.
  • We honour a wait of up to 24 hours. A longer Retry-After is read as 24 hours.
  • A 429 without a usable Retry-After pauses scheduled work for 15 minutes.
  • A request a person makes still reaches your Agent, for example a test you run from the Agent page. If your Agent refuses that request with a 429 as well, the answer says the Agent asked us to wait and gives the time.
  • While the wait lasts, the source’s health shows it as waiting, not as failing; see A source’s agent asked Apostra to wait.

Keep capabilities current

What it is. Update capability, account, and Product declarations whenever the upstream system changes what your Agent can do. Why buyers care. Current declarations prevent a buyer from selecting inventory that has changed, disappeared, or no longer supports a required feature. How we measure it. We use the current responses from our calls and compare them with the behaviour we observe. If the two disagree, the declarations-match- behaviour requirement applies.

The publisher file names the URL you connect

What it is. A publisher says which agents may sell its inventory in the authorized_agents list of its adagents.json. The url of an entry must be exactly the endpoint your Agent is connected at, path and trailing slash included. AdCP treats the path as part of an agent URL, so two spellings are two agents: an entry for https://agent.example.com does not authorize an Agent connected at https://agent.example.com/mcp, and the reverse. Apostra compares URLs the way the AdCP SDK does (canonicalizeAgentUrl): the host is not case sensitive and a default port does not count, but nothing else is ignored. Why buyers care. Under AdCP, an Agent the publisher file does not name is not authorized to sell that publisher’s inventory. Its properties read as claimed but not authorized, buyers do not see the publisher in the storefront’s list of publishers, and a buyer that checks the file may refuse to buy that inventory through your Agent. Apostra does not treat a near match as authorized, however close the spelling is. How we measure it. Each time Apostra reads a publisher file for a storefront that uses your Agent, it compares the url of every entry with the URL your Agent is connected at. When no entry names that URL, but an entry names the same host with another path or trailing slash, Apostra keeps that entry. The finding certification.publisher_authorization_url names both URLs and the publishers whose file does this. It is advisory and reported only: it stops neither certification nor buying, it never becomes the headline, and it does not change who is authorized. It clears when the publisher is re-read and an entry names the URL you connected, or when you reconnect the inventory source at the URL the file lists. How to fix it. Make the two URLs identical, in either place:
  • Ask the publisher to change the url of the entry to the exact URL your Agent is connected at, for example https://agent.example.com/mcp. If you also host the file, change it yourself.
  • Or reconnect the inventory source at the URL the file lists.
Then re-check the publisher with refresh on save_coverage, as Publisher adagents.json entry describes.

What a behaviour finding does

A flag is an attention finding: it tells you what we observed and how to fix it. A blocker is also an attention finding. On a check that can stop new buys, a blocker on an active Source stops the agent’s certification pass counting, and an agent without a current certification exemption takes no new buys until it is fixed. A blocker on a pending Source stops nothing until that Source is active. On every other check it stops nothing. Running buys continue. get with kind: "agent" shows each finding’s severity, and Findings: what needs your attention says what each severity means. How certification treats live traffic is in How certification works.

AdCP request fields accepted finding

Accept every request field defined by the AdCP version your agent serves, and ignore unknown optional fields. The behaviour baseline reports when a schema-valid request is rejected because of a defined field. This finding is report-only and does not block certification or buying.