Skip to main content
The Audience Targeting API lets you read your project’s audience targetings and targeting options. Use it to find the targeting IDs and option IDs to put in 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:read scope. 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.
Call the API from your server only. Don’t put API keys in apps or web pages.

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 the audience-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

Returns 200 with an array of targeting objects.

Get a Targeting

Returns one targeting.

Request

Request Example

Response

Returns 200 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 with parent.

Request

Query Parameters

Request Example

Response Example

Returns 200 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 users is 0, user statistics may not have built up yet, or they may have been temporarily unavailable. Don’t judge an option by a single 0. 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 next was deleted or moved in the meantime, the API returns 404 TARGETING_CATEGORY_NOT_FOUND. Read again from the first page.

Errors

  • 400 TARGETING_CATEGORY_NOT_SUPPORTED: parent is 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: next isn’t a top-level option of this targeting (it was deleted or moved), or parent isn’t an option of this targeting.

Get an Option

Returns one option with its conditions.

Request

Request Example

Response Example

Returns 200 with an option object plus the following fields. users isn’t included.
You can only get options that belong to an audience targeting in this project.

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 all or any. If there’s only one condition, it’s { "all": [condition] }.
  • Nodes of the same kind aren’t nested. For example, an all never sits directly inside an all.
For example, the following conditions match “(users whose country is KR or JP, whose 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’s conditions 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 outer any. 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 any around 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 include statusCode. 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.

Limits