Skip to main content
A storefront on Apostra lists the signals its inventory can target, such as audience segments from a data provider, through AdCP get_signals. You can then target one of those signals on a package in create_media_buy. Most of this page is for anyone who calls a storefront’s AdCP endpoint directly, with their own agent or SDK. If you buy through Apostra, see Searching a seller’s signals in Apostra.

What a storefront returns

A storefront returns the signals its inventory sources report to Apostra. It keeps them in a catalog that Apostra refreshes in the background, the same way it keeps the catalog of products. Each signal carries: The get_signals answer names none of the storefront’s inventory sources, their accounts or their own ids for a signal. When the storefront’s signal catalog holds a signal, a product from get_products names it in its signal options and included signals with the same signal_ref and signal_agent_segment_id that get_signals returns. A product can still carry an inventory source’s own reference: when that source’s signals could not be refreshed or were for one account only, or for a signal get_signals does not list. You can target such a reference on a buy as it is. When some of a seller’s signals could not be read from its inventory sources, or a new inventory source’s signals have not been read yet, the answer carries incomplete with scope signals: the list may be missing some, so ask again later. An inventory source that does not offer signals at all leaves the answer complete.

Two ways to ask

get_signals has two modes.
  • discovery_mode: "wholesale" returns every signal you can use, sorted by name, in pages of up to 100 (50 by default). The answer carries wholesale_feed_version and pricing_version. Send them back as if_wholesale_feed_version and if_pricing_version and the storefront answers unchanged: true when nothing changed.
  • discovery_mode: "brief" (the default) looks signals up. Send signal_refs to read particular signals, signal_spec to search by words, or both. A signal_spec match is a word match against each signal’s name, description, provider and categories, ranked by how many of your words it contains. A signal_spec can be up to 500 characters, and a request can look up at most 100 signal_refs and signal_ids together; a larger request is refused with INVALID_REQUEST.
Both modes take filters (catalog_types, data_providers, max_cpm, max_percent, min_coverage_percentage), countries and destinations. A signal that names no countries is not limited by country. destinations matches when it names the storefront’s own endpoint. Each of destinations, countries, data_providers and catalog_types takes at most 250 values; a longer list is refused with INVALID_REQUEST. Page through with pagination.cursor. A cursor belongs to the answer it came from: if the storefront’s signals change while you page, the next page is refused with INVALID_REQUEST and you start again without a cursor. get_signals needs AdCP 3.1 or later. A request pinned to 3.0 is refused with VERSION_UNSUPPORTED, because AdCP 3.0 requires a price and coverage figure on every signal, which a source need not report. On 3.1 and later, get_adcp_capabilities lists signals with signals.discovery_modes: ["brief", "wholesale"].

What an account changes

account is optional.
  • Without an account you get every signal the storefront’s live inventory sources report, as a public answer (cache_scope: "public"). A source whose own signal list was for one account only is left out.
  • With an account you get only the signals from the inventory sources that account can buy through (cache_scope: "account"). The feed and pricing versions belong to that account’s view. The account is checked the way product discovery checks it: an account_id must be one you hold, and a brand and operator are accepted only as another name for an account you already synced. See Discovering products on a storefront needs an account.

The signal reference

Most signals carry a signal_ref that names the storefront as the source:
The signal_id stays the same for as long as the source keeps reporting the signal and Apostra keeps the key it is derived with. If Apostra changes that key, every storefront’s signal_ids change at once. A reference you already hold keeps working on a buy while Apostra still accepts the earlier key. A buy that sends a reference Apostra no longer accepts is refused with invalid_signal_targeting_groups, and you call get_signals again for the current references. The signal_id reveals nothing about the source. A signal the source names by its data provider’s published reference (scope: "data_provider", with data_provider_domain) keeps that reference, so the same provider signal reads the same on every seller that carries it. A storefront reference names the storefront, not the provider, so you cannot check the seller’s right to resell a provider’s signal through that provider’s adagents.json.

Targeting a signal on a media buy

Send the signal_ref in a package’s targeting_overlay.signal_targeting_groups on create_media_buy or update_media_buy:
The storefront sends the signal to the inventory source that sells the package’s product, as that source’s own reference. A signal must come from the same inventory source as the product. If it does not, or the storefront does not know the reference, the request is refused at once with INVALID_REQUEST and the reason invalid_signal_targeting_groups, before any seller approval, and nothing is sent to the source. Send the signal_source_url exactly as the storefront returned it: the same reference under another address for the storefront is refused. Call get_signals again for current references and send the package again. When the signal has pricing_options, AdCP has you send the pricing_option_id of the price you choose in the signal’s entry. On a product a storefront puts together for your brief, a priced signal is buyable when the product’s seller bills it; see Priced signals below. The create_media_buy answer echoes each package’s signal_targeting_groups as you sent them, with the storefront’s references. On update_media_buy, a package’s targeting_overlay changes only the dimensions you send, as AdCP defines: leave signal_targeting_groups out to keep the package’s signals, or send null to clear them.

Signals on a storefront’s own products

A product a storefront puts together for your brief lists its signals in AdCP fields, with the same signal_ref that get_signals returns.
  • included_signals are signals built into the product. They describe what the product is, its price already covers them, and you do not select them. A product with exact age targeting lists its age first, with its data provider in ext.apostra.data_provider. Each other included signal carries its provider in data_provider, as get_signals does.
  • signal_targeting_allowed: true means you can add signals to a package of the product through targeting_overlay.signal_targeting_groups. A product says so when the inventory it is sold from runs on Apostra’s embedded sales agent and the product is not guaranteed. A fixed-price (guaranteed) package takes no added signals for now: its delivery was forecast without them, and a narrow audience could keep it from delivering. A buy or update that adds signals to a package whose pricing option is fixed-price is refused at once with invalid_signal_targeting_groups. On a product with both a fixed and an auction price, choose the auction one to add signals.
  • signal_targeting_options lists up to 20 signals from that inventory that you can add, chosen for the brief the product was put together for: the storefront picks the signals that suit the audience the brief describes, best fit first, whatever words they are named in. When it picks none it can offer, the list is the widest-reaching signals instead: highest coverage_percentage, then by name. get_signals is the full menu: a package can target any signal it serves for that inventory, subject to the checks below. Each option carries its signal_ref, the signal_agent_segment_id get_signals serves, name, description, data_provider and value type. When the product’s seller bills a selected signal’s price (see Priced signals), the options include priced signals, each with only the pricing_options the product’s price can take: in its currency, priced per impression. Otherwise they are the publisher’s own data that costs nothing, and carry no pricing_options. A third party’s data with no price is not offered, since its data cost is unknown, and neither is an age signal.
  • An option you can only use to exclude an audience says allowed_targeting_modes: ["exclude"].
  • Each option’s selection_group names the ad-server targeting it uses (audience_segment, custom_key_value or gam_custom_key), and signal_targeting_rules lists those groups. An any group can’t mix them. An option that combines several targeting criteria has a selection_group of its own: it can’t be an alternative to any other signal.
If the storefront could not read all of an inventory source’s signals when it answered, or had not read a new source’s signals yet, a product from that inventory lists none of them, rather than a partial list: its included_signals list at most its age, and it has no signal_targeting_options. It still says signal_targeting_allowed: true, and get_signals is the menu: its answer carries incomplete with scope signals whenever the catalog read was partial.

Priced signals

On a product a storefront puts together, a signal with a price is buyable when the seller’s ad server bills a selected signal’s price on the line item it books. Apostra’s embedded sales agent does this on Google Ad Manager. On other inventory, a buy that selects a priced signal in an any group is refused at once with INVALID_REQUEST and the reason invalid_signal_targeting_groups, before any seller approval: choose a signal from the product’s signal_targeting_options and send the package again. When the seller bills it:
  • Name the price you choose with pricing_option_id in the signal’s entry. An entry for a priced signal with no pricing_option_id, or one that is not among the signal’s pricing_options, is refused.
  • The storefront passes a pricing_option_id to the seller only for a price it charges you. One you send for a free signal, for a signal in a none group, or for a signal the product already includes is not passed on, so the seller can’t bill it.
  • An entry that names a pricing_option_id the storefront can’t check is refused at once, before any seller approval. That happens when the storefront can’t find the signal among the seller’s signals, whatever reference you used: name it by the signal_ref get_signals returns. It also happens when the storefront hasn’t read all of that seller’s signals just now (retry shortly), and when the package’s product is one the seller sells as is rather than one the storefront put together, unless that seller is Apostra’s embedded sales agent billing signal prices or has passed priced-signal certification (see Priced signals on products a seller sells as is).
  • The price is added to the package’s rate. A cpm price adds its CPM. A percent_of_media price adds that share of the package’s bid_price, capped at its max_cpm; a package with no bid_price is refused. Signals in one child group are alternatives, so only the highest price in each group is charged, and the groups’ prices add up. A $2 CPM signal on a package bidding $10 CPM books at $12 CPM, and delivery reports that rate and its spend.
  • The price must be in the currency of the package’s pricing option, and the package must be priced by CPM. Otherwise the buy is refused.
  • A signal in a none group only excludes an audience and is not charged, unless the signal can only exclude.
  • A signal the product already includes is covered by the product’s price. If you send a pricing_option_id for it, the storefront does not pass it to the seller, and you are not charged for it again.
  • The product’s price includes the data price of its own priced signals, and the seller bills that data on its line item. On an auction package the storefront sends your bid_price to the seller as a media bid, less the data price, so the line item’s rate, media plus data, is your bid: a $2 CPM included signal on a package bidding $12 CPM books a $10 media bid. A percent_of_media price is taken of that media bid, for an included signal and for one you add. A bid that would leave less than the seller’s own floor for media is not sent, and the buy fails with invalid_signal_targeting_groups: bid at least the product’s floor_price. What you pay doesn’t change. An update can’t change the bid_price or bidding of such a package, since its media bid was set when it was booked: add a new package with the new bid through new_packages instead.
  • A package’s signal price is set when it is booked. An update can’t add, remove or change a priced signal on a booked package: add a new package with it through new_packages instead. On a package charged a percent_of_media price, an update also can’t regroup its priced signals or change its bid_price or bidding, since the price was taken of the bid it was booked with.

Priced signals on products a seller sells as is

These products come from the seller’s own catalog: the storefront passes them through rather than putting them together for your brief. Apostra’s embedded sales agent. On a product the embedded sales agent sells as is, a priced signal is buyable when the agent bills a selected signal’s price on the line item it books, as it does on Google Ad Manager: the same condition as on a product a storefront puts together. When it does:
  • Name the price you choose with pricing_option_id in the signal’s entry. It must be one of the prices get_signals serves for the signal, which are the ones the agent bills. A price only the product lists in its signal_targeting_options is refused.
  • The price is added to the package’s rate, and that is what you pay: the product’s fixed price, or your bid_price on an auction package. A $1 CPM signal on a product priced at $15 CPM books at $16 CPM. A percent_of_media price adds that share of the same rate, capped at its max_cpm; on an auction package with no bid_price it is refused.
  • Signals in one child group are alternatives, so only the highest price in each group is charged, and the groups’ prices add up, as the agent bills them. AdCP pricing groups don’t change this.
  • A fixed-price package can take priced signals on these products.
  • An entry for a priced signal with no pricing_option_id is refused: name one of its prices.
  • A package’s signal prices are set when it is booked. Once a package has a priced signal, an update that names its signal_targeting_groups is refused, even unchanged: leave them out to keep them, or add a new package through new_packages. A package charged a percent_of_media price also can’t change its bid_price or bidding.
When the agent doesn’t bill signal prices, a package that names a pricing_option_id for one of its priced signals is refused at once with invalid_signal_targeting_groups, before any seller approval, and the reason says the seller doesn’t bill signal prices. Other sellers. On another seller’s product, priced signals aren’t available yet. They open for a seller once its sales agent passes Apostra’s priced-signal certification, and no seller can pass today: the part of the check that confirms a seller billed the price once isn’t built yet. Until a seller passes, a package that names a pricing_option_id for one of its priced signals is refused at once with invalid_signal_targeting_groups, before any seller approval, and the reason says the seller hasn’t passed. A priced signal sent without a price is sent and charged nothing, as before. See Certification. A seller will pass when a certification test buy that selected a priced signal was accepted as sent, delivery was reported, and the seller billed the media rate plus that signal’s price, once. A pass counts while the evidence it judged is less than seven days old. The rest of this section describes buying from a seller that has passed. When the seller has passed:
  • Name the price you choose with pricing_option_id in the signal’s entry. An entry for a priced signal with no pricing_option_id is refused.
  • When the product lists the signal in its own signal_targeting_options, the prices listed there are the ones the seller bills on that product. A signal it lists without prices is bundled into the product’s price or costs nothing extra on it, so it is free. For a signal the product doesn’t list, the prices get_signals serves apply.
  • The storefront sends the signal to the seller as the seller’s own reference, with the pricing_option_id you named.
  • The price is added to the package’s rate, and that is what you pay. A cpm price adds its CPM: a $1.75 CPM signal on a product priced at $8 CPM books at $9.75 CPM. A percent_of_media price adds that share of the package’s rate, capped at its max_cpm, and only on a fixed-price package: on an auction package the seller takes it of a clearing price that isn’t known when the package is booked, so it is refused. A flat fee, or any other price that isn’t charged per impression, can’t be bought this way. Every price must be in the currency of the package’s pricing option, on a package priced by CPM.
  • Each signal you select is charged once, whatever child group it is in. A seller can put signals in a pricing group (AdCP pricing_group) and charge only the highest cpm price of the ones you select from it (highest), or each one (each). A percent_of_media price is always charged on its own. The rules come from the seller’s own get_signals answer (signal_pricing_group_rules), and a rule the product states in its signal_targeting_rules replaces the seller’s for that group. A group with no rule is charged each, as AdCP sets out.
  • Apostra stores the seller’s get_signals rules each time it reads the seller’s signals in full, and reads them in full until it has stored them. Until then, or when the rules the seller or the product declares aren’t valid AdCP, a package that selects two or more priced signals from one pricing group whose rule isn’t known is refused: select one of them.
  • A package’s signal prices are set when it is booked, and the seller may reprice its options later. So once a package has a priced signal, an update that names its signal_targeting_groups is refused, even when the signals are unchanged: leave signal_targeting_groups out of the update to keep them. To select different priced signals, add a new package through new_packages. An update can’t add a priced signal to a package booked without one either.
  • If Apostra can’t read whether the seller has passed just now, a package that names a pricing_option_id for one of its signals is refused with a reason to retry shortly.

Groups the seller’s ad server can apply

Signals in an any group are alternatives, and the seller’s ad server can make alternatives only of audience segments, or of values of one custom-targeting key. A buy is refused at once with invalid_signal_targeting_groups, before any seller approval, when an any group:
  • mixes audience segments with custom-targeting key signals (custom_key_value or gam_custom_key);
  • holds values of more than one custom-targeting key;
  • holds a signal that combines several targeting criteria together with other signals; or
  • holds a signal that can only exclude.
Values of one key, such as two key=value signals on the same key, can be alternatives in one any group. A group with a single signal takes any signal except one that can only exclude. A none group excludes each of its signals separately, so it takes any mix. A signal_ref that names more than one of the seller’s signals is refused the same way: send the signal’s signal_agent_segment_id with it. The same rules apply to the signal groups a storefront product stores. A storefront does not compose a product that offers signals as alternatives the seller’s ad server can’t book, such as two age bands that sit on different custom-targeting keys. A product stored that way before the rule existed is refused at once with invalid_signal_targeting_groups, before the buy is sent to the seller. The message names the group and its signals; choose another product, or ask the seller to recompose it. A seller whose sales agent declares that it books any signal combination on every product of the buy is not held to these rules.

Searching a seller’s signals in Apostra

A buyer account in Apostra reads one seller’s signals with search, the same read a buyer’s own agent makes through the Apostra MCP server or HTTP API:
  • filter.sellerAccountId names the seller by its Account id, the sellerAccountId on a seller or product result. One search reads one seller.
  • filter.advertiserId names the advertiser whose account with that seller is used. Apostra asks the seller’s storefront get_signals with that account, so you see only the signals from the inventory sources the account can buy through (see What an account changes). When your account has only one active advertiser, it is filled in for you.
  • query searches by words, as signal_spec does in brief mode. Without a query you get the seller’s whole list, sorted by name.
  • filter.dataProvider keeps only signals from these data providers. It matches the provider’s name exactly, ignoring case, so copy the name from an earlier result. To search by part of a provider’s name, such as “Polk”, put it in query.
  • limit sets the page size, up to 100 (50 by default). For the next page, send the returned nextCursor as cursor, with the same query and filters.
Each result is the signal as the storefront returns it, without deployments. The search is refused, never answered with an empty list, when:
  • your advertiser has no account with the seller yet, or the account needs attention: open Media Partners to see where it stands;
  • the seller is a platform such as Meta or Snap, which does not offer a signal catalog through Apostra. That does not mean it has no signals.
To target a signal, put its signal_ref unchanged in targetingOverlay.signal_targeting_groups on that seller’s product in save_media_buy, with its value_type (a binary signal takes value: true). A signal can be targeted only on products of the inventory source that reports it; any other pairing is refused with invalid_signal_targeting_groups, as described in Targeting a signal on a media buy.