> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience Targeting API

> Learn how to read audience targetings, targeting options, and option conditions from your server with an API key.

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](https://docs.adrop.io/integrations/ad-products.md), or to check the property and event conditions set on an option.

> [!NOTE]
>
> This API is read-only. To create or update audience targetings, use the console. See [Creating Audience Targeting](https://docs.adrop.io/targeting/audience.md). For context targeting, use the [Context Targeting API](https://docs.adrop.io/integrations/context-targeting/overview.md).

***

## 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](https://docs.adrop.io/integrations/ad-products.md) scopes on the same key.

> [!WARNING]
>
> Call the API from your server only. Don't put API keys in apps or web pages.

***

## Basics

| Item | Value |
| - | - |
| Base URL | `https://lake.adrop.io` |
| Authentication | Put the API key in the `x-api-key` header. You can only read targetings in the key's project. IDs from other projects return `404`. |
| Request body | All requests are reads (`GET`), so don't send a body. A request with a body returns `413` regardless of its size. |
| ID format | A string of up to 64 letters, digits, `_`, and `-`. |
| Timestamps | `createdAt`, `updatedAt`, and `segmentedAt` are epoch milliseconds. This differs from the Context Targeting API, which uses ISO 8601 strings. |
| Concurrent requests | Up to 4 per project at a time, counted across all keys of the same project. More return `429`. |

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.

| API | Console term | Description |
| - | - | - |
| `targeting` | Targeting | An audience targeting, such as "Age". The API handles audience targetings only. |
| `category` | Targeting option (option) | An option in a targeting, such as "20s". |
| `type: "collection"` | Option group | An option that groups sub-options. A regular option has `type: "atomic"`. |
| `children`, `parent` | Sub-option | An option inside an option group. An option group's `children` lists its sub-options, and a sub-option's `parent` is its option group. |
| `users` | Audience size | The number of the project's users who belong to this option. |
| `conditions` | Conditions | The property and event conditions set on the option. |

***

## Endpoints

Paths are relative to the Base URL. All endpoints require the `audience-targeting:read` scope.

| Method | Path | Description |
| - | - | - |
| `GET` | `/audience-targeting` | [List targetings](#list-targetings) |
| `GET` | `/audience-targeting/{targetingId}` | [Get a targeting](#get-a-targeting) |
| `GET` | `/audience-targeting/{targetingId}/categories` | [List options](#list-options) (page by page) |
| `GET` | `/audience-targeting/category/{categoryId}` | [Get an option](#get-an-option) (with conditions) |

***

## Targeting Object

| Field | Type | Description |
| - | - | - |
| `_id` | string | Targeting ID. Use it in `targetings[].targeting` of an ad product. |
| `name` | string | Targeting name |
| `categoryCount` | number | Number of options, including sub-options. It can include deleted options, so it may differ from the number you read with [List Options](#list-options). |
| `segmentedAt` | number | When the audience of this targeting was last calculated. Omitted if it hasn't been calculated yet. |
| `createdAt` | number | When the targeting was created |
| `updatedAt` | number | When the targeting was last updated |

The targeting object doesn't include options. Read options with [List Options](#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

```http theme={null}
GET /audience-targeting
```

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response Example

Returns `200` with an array of [targeting objects](#targeting-object).

```json theme={null}
[
  {
    "_id": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
    "name": "Users",
    "categoryCount": 12,
    "segmentedAt": 1790820300000,
    "createdAt": 1790820300000,
    "updatedAt": 1790820300000
  }
]
```

***

## Get a Targeting

Returns one targeting.

### Request

```http theme={null}
GET /audience-targeting/{targetingId}
```

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response

Returns `200` with a [targeting object](#targeting-object).

### Errors

* `404 TARGETING_NOT_FOUND`: The targeting doesn't exist, belongs to another project, or is a context targeting.

***

## Option Object

| Field | Type | Description |
| - | - | - |
| `_id` | string | Option ID. Use it as a key in `targetings[].policies` of an ad product. |
| `name` | string | Option name |
| `type` | string | `atomic` (regular option) or `collection` (option group) |
| `parent` | string | ID of the option group the option belongs to. Only on sub-options. |
| `children` | string\[] | The first 50 sub-option IDs. Only on option groups. |
| `childCount` | number | Total number of sub-options. Only on option groups. If it's larger than the length of `children`, read the rest with the `parent` parameter of [List Options](#list-options). |
| `users` | number | Audience size. Only in List Options responses. |
| `operable` | boolean | Whether the properties used in the conditions match the current property settings (fields, types, and operators). See [When Conditions Can't Be Read](#when-conditions-cant-be-read). |
| `createdAt` | number | When the option was created |
| `updatedAt` | number | When the option was last updated |

[Get an Option](#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

```http theme={null}
GET /audience-targeting/{targetingId}/categories
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `limit` | number | - | `100` | Number of options per page (1–1,000) |
| `next` | string | - | - | Cursor for the next page. Pass the `next` value from the previous response as is. Omit it for the first page. |
| `parent` | string | - | - | Option group ID. If set, returns the sub-options of that option group in their order within the group. |

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV/categories?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response Example

Returns `200` with `items` (a list of [option objects](#option-object)) and `next` (the cursor for the next page). If there's no `next`, this is the last page.

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
      "name": "Korea",
      "type": "atomic",
      "users": 1200,
      "operable": true,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    },
    {
      "_id": "01JAZ3KC3D4E5F6G7H8J9K0M1N",
      "name": "Asia",
      "type": "collection",
      "users": 5000,
      "operable": true,
      "children": ["01JAZ3KB2C3D4E5F6G7H8J9K0M", "01JAZ3KE5F6G7H8J9K0M1N2P3Q"],
      "childCount": 2,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KC3D4E5F6G7H8J9K0M1N"
}
```

* The option list doesn't include conditions. Read conditions with [Get an Option](#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

```http theme={null}
GET /audience-targeting/category/{categoryId}
```

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/category/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response Example

Returns `200` with an [option object](#option-object) plus the following fields. `users` isn't included.

| Field | Type | Description |
| - | - | - |
| `targeting` | string | ID of the targeting the option belongs to |
| `convertible` | boolean | Whether the conditions can be expressed as `conditions` |
| `conditions` | object | The option's conditions. Only present when `convertible` is `true`. See [Conditions](#conditions). |

```json theme={null}
{
  "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
  "name": "Korean adults",
  "type": "atomic",
  "operable": true,
  "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
  "convertible": true,
  "conditions": {
    "all": [
      { "field": "country", "op": "is", "values": ["KR"] },
      { "field": "age", "op": "greater_than_or_equals", "values": [20] }
    ]
  },
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

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

| Node | Meaning |
| - | - |
| `{ "all": [...] }` | Every condition inside is met |
| `{ "any": [...] }` | At least one condition inside is met |
| Property condition, event condition | Described below |

* 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)".

```json theme={null}
{
  "any": [
    {
      "all": [
        { "field": "country", "op": "is", "values": ["KR", "JP"] },
        { "field": "custom.level", "op": "greater_than_or_equals", "values": [10] },
        {
          "event": "purchase",
          "action": "did",
          "measure": "total_events",
          "op": "greater_than_or_equals",
          "value": 1,
          "where": [{ "param": "item_category", "op": "is", "values": ["book"] }],
          "recency": "30D"
        }
      ]
    },
    { "field": "gender", "op": "is", "values": ["F"] }
  ]
}
```

### Property Conditions

```json theme={null}
{ "field": "country", "op": "is", "values": ["KR"] }
```

| Field | Description |
| - | - |
| `field` | Property. The default properties are `country`, `language`, `gender`, `age`, and `consent`. A custom property is `custom.<property name>`. See [Properties](https://docs.adrop.io/targeting/property.md). |
| `op` | Operator. See the table below. |
| `values` | Values to compare. How many depends on the operator: one or more for `is` and `is_not`, two (`[min, max]`) for `between` and `not_between`, none (`[]`) for `is_true` and `is_false`, and one for the others. |
| `match` | Only on custom properties whose value is an array. With `any`, at least one element of the array must meet the condition. With `all`, every element must. |

| Property type | Operators |
| - | - |
| String | `is` (equals one of the values), `is_not` (equals none of the values, including users with no value), `contains`, `does_not_contains`, `starts_with`, `ends_with` |
| Number | `is`, `is_not`, `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `between`, `not_between` |
| Boolean | `is_true`, `is_false` |
| Date | `last` (within a recent period), `before_the_last`, `next`, `after_the_next` (the value is a period such as `30D`, `2W`, or `1M`), `before`, `after` (the value is a date string) |

### Event Conditions

```json theme={null}
{ "event": "purchase", "action": "did", "measure": "total_events", "op": "greater_than_or_equals", "value": 1, "recency": "30D" }
```

| Field | Description |
| - | - |
| `event` | Event name: `app_open`, `sign_up`, `push_clicks`, `page_view`, `click`, `view_item`, `add_to_wishlist`, `add_to_cart`, `begin_checkout`, `purchase`, `view_content`, `begin_lead_form`, or `generate_lead`. See [Events](https://docs.adrop.io/targeting/event.md). |
| `action` | `did` matches users who did the event within the period and whose aggregated value meets `op` and `value`. `did_not_do` matches users who didn't do the event within the period, and has no `measure`, `op`, or `value`. |
| `measure` | Aggregation. Either `"total_events"` (number of events), or the `sum`, `average`, `minimum`, `maximum`, or `distinct_count` (number of distinct values) of an event parameter's values, as in `{ "type": "sum", "param": "price" }`. |
| `op` | `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, or `less_than_or_equals` |
| `value` | The number to compare |
| `where` | List of event parameter conditions, `[{ "param", "op", "values" }]`. All of them must be met. |
| `recency` | Period, written as a number followed by a unit: `H` (hours), `D` (days), `W` (weeks), or `M` (months), for example `30D`. Only events within this period count. |

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

| Field | Meaning | When `false` |
| - | - | - |
| `convertible` | Whether the stored conditions can be expressed as a tree with the same meaning as in ad serving | There's no `conditions`. Don't interpret the conditions yourself. Check them in the console. |
| `operable` | Whether the properties used in the conditions match the current property settings | A property used in the conditions was deleted or its type changed, so the option can't run with the current settings. For an option group, it's `false` if any sub-option doesn't match. |

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.

| Status | `errorCode` | Cause |
| - | - | - |
| `400` | `VALIDATION_FAILED` | An ID, `next`, or `parent` has an invalid format, `limit` is out of range, or you sent an unknown query parameter. |
| `400` | `TARGETING_CATEGORY_NOT_SUPPORTED` | `parent` is a regular option, not an option group. |
| `401` | - | The API key is missing, invalid, or revoked. |
| `403` | - | The key doesn't have the `audience-targeting:read` scope. |
| `404` | `TARGETING_NOT_FOUND` | The targeting doesn't exist, belongs to another project, or is a context targeting. |
| `404` | `TARGETING_CATEGORY_NOT_FOUND` | The option doesn't exist, belongs to another project, or isn't an option of an audience targeting. List Options also returns it when `next` or `parent` isn't an option of this targeting. |
| `413` | - | A read request has a body. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | The concurrent request limit was exceeded, or the server is busy. Wait for the number of seconds in the `Retry-After` header, then resend. |
| `502` | - | Internal server communication failed. |

***

## Limits

| Item | Limit |
| - | - |
| Option list page size | 1–1,000 (default 100) |
| `children` of an option group | The first 50. Get the rest with `parent`. |
| Concurrent requests | 4 per project |
| Response download | If you don't receive the whole response within 30 seconds, the server closes the connection. Option groups with many sub-options can have large responses. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.