targetings of the Ad Product API, or to check the property and event conditions set on an option.
This API is read-only. To create or update audience targetings, use the console. See Creating Audience Targeting. For context targeting, use the Context Targeting API.
Prerequisites
- You need an API key with the
audience-targeting:readscope. You can’t select this scope in [Settings] > [Integrations] in the console. Ask Adrop, and we’ll issue you a key with the scope. You can get the Ad Product API scopes on the same key.
Basics
When you get
429, wait for the number of seconds in the Retry-After header, then send the request again. When the server is busy, you can get 429 even if you send requests one at a time.
Terms
Some API paths and fields use different names from the console. This page uses the console’s terms.Endpoints
Paths are relative to the Base URL. All endpoints require theaudience-targeting:read scope.
Targeting Object
The targeting object doesn’t include options. Read options with List Options.
List Targetings
Returns all audience targetings in the project at once, without pagination, in the order they appear in the console. Context targetings aren’t included.Request
Request Example
Response Example
Returns200 with an array of targeting objects.
Get a Targeting
Returns one targeting.Request
Request Example
Response
Returns200 with a targeting object.
Errors
404 TARGETING_NOT_FOUND: The targeting doesn’t exist, belongs to another project, or is a context targeting.
Option Object
Get an Option also returns
targeting (the ID of the targeting the option belongs to), convertible, and conditions.
List Options
Returns the top-level options of a targeting, one page at a time, in the order they appear in the console. Read the sub-options of an option group separately withparent.
Request
Query Parameters
Request Example
Response Example
Returns200 with items (a list of option objects) and next (the cursor for the next page). If there’s no next, this is the last page.
- The option list doesn’t include conditions. Read conditions with Get an Option.
- If
usersis0, user statistics may not have built up yet, or they may have been temporarily unavailable. Don’t judge an option by a single0. If in doubt, get it again after a short wait. - If options are added, deleted, or moved while you’re reading pages, the results may not match the actual options. If the option you passed as
nextwas deleted or moved in the meantime, the API returns404 TARGETING_CATEGORY_NOT_FOUND. Read again from the first page.
Errors
400 TARGETING_CATEGORY_NOT_SUPPORTED:parentis a regular option, not an option group.404 TARGETING_NOT_FOUND: The targeting doesn’t exist, belongs to another project, or is a context targeting.404 TARGETING_CATEGORY_NOT_FOUND:nextisn’t a top-level option of this targeting (it was deleted or moved), orparentisn’t an option of this targeting.
Get an Option
Returns one option with its conditions.Request
Request Example
Response Example
Returns200 with an option object plus the following fields. users isn’t included.
Errors
404 TARGETING_CATEGORY_NOT_FOUND: The option doesn’t exist, belongs to another project, or doesn’t belong to an audience targeting.
Conditions
conditions is a tree that combines the option’s conditions with all (and) and any (or). It has the same meaning as the conditions actually used in ad serving.
Nodes
- The outermost node is always
allorany. If there’s only one condition, it’s{ "all": [condition] }. - Nodes of the same kind aren’t nested. For example, an
allnever sits directly inside anall.
level is 10 or more, and who made at least one purchase with an item_category of book in the last 30 days) or (users whose gender is F)”.
Property Conditions
Event Conditions
When you join multiple event conditions in the console, ad serving combines them by fixed rules. As a result, conditions joined with or in the console can appear as
all in the tree. Follow the all and any in the tree as they are.
Option Group Conditions
An option group has no conditions of its own. A user belongs to it when they meet the conditions of any one of its sub-options. So an option group’sconditions are its sub-options’ conditions combined with any.
- If a sub-option’s conditions start with
any, the conditions inside it go directly into the outerany. So the number of branches can differ from the number of sub-options. - If there’s only one sub-option, its conditions are returned as is, without an
anyaround them. - Sub-options with no conditions are skipped.
When Conditions Can’t Be Read
The two values are independent.
convertible can be true while operable is false.
Error Handling
Error responses includestatusCode. Errors whose errorCode in the table below isn’t - also include errorCode. Handle errors by errorCode, or by statusCode when there’s no errorCode. For request format errors (VALIDATION_FAILED), path in detail.errors[] shows where the problem is.