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, oneapplication/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. Yourget_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. Declareagent, 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 bothsync_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 (withsandbox: truefor a sandbox account). We send brand and operator, never anaccount_id, onget_products. Oncreate_media_buyandsync_creativeswe send theaccount_idyoursync_accountsreturned until your Agent refuses it withINVALID_REQUESTonaccount.account_id. We then retry that call once with brand and operator, and keep using them for that call. - Otherwise we send the
account_idyoursync_accountsreturned, or brand and operator when it returned none.
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.
Takes buy corrections
What it is. Your Agent must listupdate_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. Declaremedia_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 awholesale_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_webhooksinget_adcp_capabilitiesand send its change events to the catalogue webhook Apostra registers throughsync_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.
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.
sentry-trace or baggage.
Declare the targeting you honour
What it is. Declare the account-wide targeting your Agent honours inget_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 withsync_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_audiencesin its tool list.- A
media_buy.audience_targetingblock.
- It takes audiences. Declare
media_buy.audience_targetinginget_adcp_capabilities, and implement and listsync_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_includeandaudience_excludeinmedia_buy.execution.targeting, so buyers are not told they can target an audience on your Agent.
Take a buyer’s audience, report it honestly and keep or refuse it
What it is. If your agent declaresmedia_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_smallorsuspended. Never reportreadywhilematched_countis belowminimum_size: AdCP says a seller MUST emittoo_smallin that case. When the status istoo_small, populateminimum_size. - Keep or refuse the include. A
create_media_buywhose package carriesaudience_includeis either accepted, and thenget_media_buysreturns the package with the audience still intargeting_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_sizeanderror.details.minimum_size, both numbers. AdCP calls this shape recommended; Apostra expects it so a buyer knows how many more members to add.
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 sendingsync_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 canonicalformat_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 callssync_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.
Responsiveness finding
Threshold. For each Source, over seven days:- Blocker: more than 5% of at least 20
get_productscalls 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. Arequest_proposalsround 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_productsis over 10 seconds, and at least one call that took more than 10 seconds returned no task handle.
- 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.
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_deliverycalls 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.
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 answeredsubmitted,
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
workingupdates.
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.
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_accountscreated a duplicate (see Account sync is idempotent finding). - The lookup matches on brand alone and ignores the operator or the sandbox flag.
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 andpayment_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
billingorpayment_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 namepayment_terms.
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 repeatsync_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.
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 anidempotency_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_secondsit declares.
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 everysync_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_accountsreports a different object thansync_accountsaccepted.
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 statesreporting_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 indaily_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 eachsync_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.
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_billinglists a billing model, such asagent, 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_buyon 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_configor 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 ignorespush_notification_configand lets the buyer polltasks/get.
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 everycreate_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
correctabledoes 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, indetails.product_ids, or as adetailsvalue that is exactly the id of a product your Agent lists inget_products. The finding names the product. We match ids exactly and never read the error message.
- 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.
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_buysreply. 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_deliveryreply, where Apostra reads the Source’s delivery by polling. The reply as your Agent sent it is checked against the AdCP delivery schema.
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
statusthat 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.
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 declaresaccount.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 eachtools/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 declareswholesale 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 oneget_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
errorsarray; - the reply left out
media_buys, held a buy with nomedia_buy_idorstatus, listed one buy twice, sentpaginationthat is not an object with a booleanhas_more, or sent acursorthat did not move on.
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
nullin a field AdCP types as an object or a list, such astargeting_overlay.frequency_caporgeo_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.
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’sbudget 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
budgetor the buy’stotal_budget, so a daily amount reads as the total. - A budget changed to daily in the ad server after the buy was placed.
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’sreporting_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_truncatedandby_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_domainand anidentifierwith atypeand avalue, plusspendand whatever other metrics you report.
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: truebut the agent only reportsby_packagetotals. - The agent returns
by_propertyonly 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_domainandidentifierAdCP asks for. - The agent returns
by_propertywithout theby_property_truncatedorby_property_suppressedflags.
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 throughget_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.
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 AdCPerrorsarray or anadcp_errorenvelope. 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.
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 arecovery 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
recoverythat is nottransient,correctableorterminal, 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.
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 asretryorfatal, a boolean for whether to retry, ornullfor 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
recoveryto the error at the top of the answer but not to the errors of each creative.
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 answersync_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’sstatus. - 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_configon 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.
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 aby_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,spendandclicksthat 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 theirspend, 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.
- The agent fills
by_creativeby 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.
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 thepackage_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_buyresponse. - The agent regenerates package ids between
create_media_buyandget_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.
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-spendget_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_ERRORuntil 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_ERRORorINVALID_REQUESTwhen AdCP gives it a structured answer. - The agent validates the brief against its own, stricter schema than the AdCP version it declares.
- With products, which may be an empty list:
get-products-response.json. - To ask the buyer for more, with task status
input-required, areasonofCLARIFICATION_NEEDEDorBUDGET_REQUIRED, andsuggestionsthat name what to add:get-products-async-response-input-required.json. - To decline a brief you understood, with task status
rejected, areasonand optionalsuggestions:get-products-rejected.json.
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 withbilling: "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 sendsync_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 anidempotency_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 arecovery, 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 anassignment_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 inchannels, 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: informat_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:
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_refthatformat_idsleaves out, first compare the two entries field by field: often the format is listed, but one side carrieswidth,heightorduration_msand the other does not. Make them identical. Otherwise add that format toformat_ids, or correct the reference if the option is a different format. - When
format_idslists a format that no option names or matches, add an option for it, or remove it fromformat_ids. - When an option sets
canonical_formats_only: true, remove itsv1_format_ref.
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 examplemain_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.
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’sPRODUCT_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. Async_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 answersync_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 oncreate_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 aspackages[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’slanding_page_urlortrackers, such aspackages[0].creative_assignments[1].trackers, when your agent does not declarecreative.supports_assignment_landing_pageorcreative.supports_assignment_trackers.
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. Onget_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 owncreative_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_idof its result insync_creatives; - take it in a package’s
creative_assignmentsinupdate_media_buy, and report the package as holding it increative_approvalsonget_media_buys; - list the creative under that id in
list_creatives, and report its delivery under that id in theby_creativerows ofget_media_buy_delivery; - use that id, unchanged, in every asynchronous
sync_creativescallback and in any review verdict it reports for the copy, includingcreative_approvalsonget_media_buys.
~, 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. Inget_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 async_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_includeandaudience_exclude.
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_audiencesonly when its audience support takes members or backs audience targeting on a buy. - Its readiness report flags a platform that lists
sync_audienceswith no passing audience canary in the last 30 days.
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 acontext, 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 AdCPopportunity 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. Onget_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. Answerget_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 whosestart_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: anagent_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_listover MCP. This is how the AdCP SDKs resolve a reference, for exampleresolvePropertyListin@adcp/sdk/server. Call theget_property_listtool on the MCP server atagent_url, with the reference’sauth_tokenas the bearer credential. The list is in the tool result’sstructuredContent. Send it as its own request: inside a JSON-RPC batch it is refused. - REST.
GET {agent_url}/lists/{list_id}withAuthorization: Bearer {auth_token}.
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 throughupdate_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_buycarries the reference now in effect on each package. Resolve itslist_idand confirm the update. - New contents, same reference. When only a list’s contents change, the
reference and its
list_idstay the same, butupdate_media_buyis still sent. Treat it as a refresh signal: fetch the current list before using a cached copy again, instead of waiting forcache_valid_until.
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-Afteris read as 24 hours. - A 429 without a usable
Retry-Afterpauses 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 theauthorized_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
urlof the entry to the exact URL your Agent is connected at, for examplehttps://agent.example.com/mcp. If you also host the file, change it yourself. - Or reconnect the inventory source at the URL the file lists.
refresh on save_coverage, as
Publisher adagents.json entry
describes.
What a behaviour finding does
A flag is anattention 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.