Option Groups - Ad Control Help Center

An option group is a targeting option that groups other options, called sub-options. With the API, you can create option groups, add and move sub-options, and choose whether advertisers can select sub-options individually. The requests on this page need an API key with the context-targeting:write scope. Reading option groups needs context-targeting:read. See Prerequisites. The examples build a Sports option group with the sub-options Baseball and Soccer in the News Sections targeting (01JAB3XK5Q8V7M2N4P6R9T0W1Y). They assume the targeting has no other option named Sports, because option names must be unique within a targeting.

What Is an Option Group

An option group matches its own Context IDs and the Context IDs of its sub-options. With the structure below, a campaign that includes Sports matches ad requests whose Context ID is sport, baseball, or soccer.

Option	Type	Own Context IDs	Matches
Sports	Option group	`sport`	`sport`, `baseball`, `soccer`
Baseball	Sub-option of Sports	`baseball`	`baseball`
Soccer	Sub-option of Sports	`soccer`	`soccer`

One level only: Sub-options are always regular options (type: "atomic"). An option group is always a top-level option and can’t contain another option group.
Never empty: An option group needs at least one sub-option or one Context ID of its own.
Unique own Context IDs: An option group’s own Context IDs can’t also be own Context IDs of another option group in the project. See Constraints.
Names: Option group and sub-option names follow the name rules and must be unique within the targeting, including option groups and sub-options. A duplicate fails with 409 TARGETING_CATEGORY_NAME_DUPLICATE.

In the option object, option groups and sub-options have these fields:

Field	Type	Description
`type`	string	`collection` for an option group. Sub-options are `atomic`.
`contextCount`	number	For an option group, the number of distinct Context IDs it matches: its own and its sub-options’
`ownContextCount`	number	Option group only. Number of its own Context IDs
`exposeChildren`	boolean	Option group only. Whether sub-options are shown to advertisers. `false` if never set
`children`	string[]	Option group only. IDs of the first 50 sub-options
`childCount`	number	Option group only. Total number of sub-options
`parent`	string	Sub-option only. ID of the option group

To read an option group:

Get an Option returns only the option group’s own Context IDs in contexts, paged with offset and limit (ownContextCount in total). Read each sub-option’s Context IDs from the sub-option.
When childCount is more than 50, list all sub-options with List Options and the parent query parameter set to the option group ID.

To rename an option group or a sub-option, or to change its Context IDs, use Update an Option as you would for any option. For an option group, contexts changes only its own Context IDs. Changes reach ad serving after a short delay. See When Changes Take Effect.

Create an Option Group

Use the same endpoint as Add an Option and send type: "collection", children, or both. Each item in children becomes a new sub-option, created together with the option group.

Request

POST /context-targeting/{targetingId}/category

Path Parameters

Parameter	Type	Required	Description
`targetingId`	string	Yes	ID of the targeting to add the option group to

Request Body

Field	Type	Required	Description
`name`	string	Yes	Option group name
`type`	string	No	`collection`. You can leave it out when you send `children`
`contexts`	string[]	No	The option group’s own Context IDs
`children`	object[]	No	Sub-options to create with the option group
`children[].name`	string	Yes	Sub-option name
`children[].contexts`	string[]	No	Context IDs of the sub-option
`exposeChildren`	boolean	No	Show sub-options to advertisers. Default `false`. See Show Sub-options to Advertisers

Send at least one item in children or one Context ID in contexts. An option group with neither fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED. So does type: "atomic" with children.
An item in children accepts only name and contexts. A sub-option can’t have sub-options of its own.
If one of the option group’s own Context IDs is already an own Context ID of another option group in the project, the request fails with 400 TARGETING_COLLECTION_CONTEXT_DUPLICATED. See Constraints.
A new option group is a new top-level option, so Effects on Ad Products and Campaigns applies to it as to any new option.

You can also create option groups when you create a targeting, with the same fields in each categories item, or with Add Options in Bulk.

Example Request

curl -X POST https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/category \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sports",
    "type": "collection",
    "contexts": ["sport"],
    "children": [
      { "name": "Baseball", "contexts": ["baseball"] }
    ]
  }'

To create an option group with only its own Context IDs, keep type: "collection" and leave out children:

{
  "name": "Sports",
  "type": "collection",
  "contexts": ["sport"]
}

Example Response

The API returns 201 with the new option group.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 2,
  "ownContextCount": 1,
  "exposeChildren": false,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8"],
  "childCount": 1,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}

Add an Option to an Option Group

To add a new sub-option to an existing option group, send parent with the option group ID to the Add an Option endpoint.

parent must be a top-level option group in the same targeting. If the targeting has no option with that ID, the request fails with 404 TARGETING_CATEGORY_NOT_FOUND. If the option isn’t an option group, it fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED.
The new option is a regular option. type: "collection", children, or exposeChildren together with parent fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED.
The option group starts matching the new option’s Context IDs. Campaigns that include the option group now also target them, and campaigns that exclude it now also exclude them. Ad product settings don’t change.

To put an existing option into an option group, see Move or Detach an Option.

Request

POST /context-targeting/{targetingId}/category

Path Parameters

Parameter	Type	Required	Description
`targetingId`	string	Yes	ID of the targeting that has the option group

Request Body

Field	Type	Required	Description
`name`	string	Yes	Sub-option name
`contexts`	string[]	No	Context IDs of the sub-option
`parent`	string	Yes	ID of the option group to add the option to

Example Request

curl -X POST https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/category \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soccer",
    "contexts": ["soccer"],
    "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
  }'

Example Response

The API returns 201 with the new sub-option.

{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:25:10.000Z"
}

Move or Detach an Option

Send parent to Update an Option to change where an option sits.

An option group ID moves the option under that option group, from the top level or from another option group.
null detaches a sub-option to the top level.

Move	Effect on ad products and campaigns
Top level → option group	The option’s own settings in ad products are removed. The move fails with `400 TARGETING_CATEGORY_LOCKED` if an ad product sets the option as Required Include or Required Exclude, or if a campaign that hasn’t ended includes or excludes it (deleted or canceled campaigns and drafts created by advertisers don’t count). Remove those settings first.
Option group → top level	The option takes over the option group’s settings in ad products and campaigns, so campaigns that included or excluded the option group still include or exclude the option’s Context IDs. If this would give an ad product more than 500 options set as Required Include or Required Exclude, the request fails with `400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`.
Option group → another option group	Ad products and campaigns don’t change.

The option group that receives the option starts matching its Context IDs, and the option group that the option leaves stops matching them.

You can’t move an option group. parent on an option group fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED.
The destination must be a top-level option group in the same targeting. Otherwise the request fails with 404 TARGETING_CATEGORY_NOT_FOUND or 400 TARGETING_CATEGORY_NOT_SUPPORTED.
You can’t move or detach the last sub-option of an option group that has no Context IDs of its own. The request fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED.

The lock applies even when the option got its Required Include, Required Exclude, or campaign include or exclude automatically, for example from its option group when it was detached or when the option group was deleted. Until that setting is removed, you can’t move the option back under an option group with the API. To keep options in an option group, create them with parent or children from the start.

Request

PATCH /context-targeting/category/{categoryId}

Path Parameters

Parameter	Type	Required	Description
`categoryId`	string	Yes	ID of the option to move

Request Body

Field	Type	Required	Description
`parent`	string or null	Yes	Option group ID to move the option under, or `null` to detach it to the top level
`name`	string	No	New name, applied together with the move. If the move fails, the name doesn’t change either

parent can’t be combined with contexts. Change Context IDs in a separate request.

Example Request

Detach Soccer to the top level:

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5TC1D2E3F4G5H6J7K9 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parent": null }'

To move it back under Sports, send the option group ID instead:

{
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
}

Example Response

The API returns 200 with the updated option. A detached option has no parent.

{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:30:00.000Z"
}

Show Sub-Options to Advertisers

By default, advertisers can select an option group only as a whole. Set exposeChildren to true to let advertisers include or exclude each sub-option on its own when they book a campaign.

Advertisers can select sub-options only when the ad product offers the option group as Free Selection. See Selling Targeting.
exposeChildren doesn’t change what the option group matches. Changing it doesn’t modify existing ad products or campaigns.
Only option groups accept exposeChildren. Sending it for any other option fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED. Send true or false; null fails with 400.
You can also set it when you create the option group.

Request

PATCH /context-targeting/category/{categoryId}

Path Parameters

Parameter	Type	Required	Description
`categoryId`	string	Yes	Option group ID

Request Body

Field	Type	Required	Description
`exposeChildren`	boolean	Yes	`true` shows sub-options to advertisers, `false` hides them

You can send name and contexts in the same request.

Example Request

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5SB1C2D3E4F5G6H7J8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exposeChildren": true }'

Example Response

The API returns 200 with the updated option group.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 3,
  "ownContextCount": 1,
  "exposeChildren": true,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8", "01JAB3XK5TC1D2E3F4G5H6J7K9"],
  "childCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:35:00.000Z"
}

Delete an Option Group

Delete an option group with Delete an Option. Its sub-options aren’t deleted:

Sub-options move to the top level and take over the option group’s settings in ad products and campaigns. For example, if an ad product sets Sports as Required Include, Baseball and Soccer become Required Include, and a campaign that included Sports now includes Baseball and Soccer.
The option group’s own Context IDs are deleted and stop matching. In the example, campaigns that included Sports no longer match sport.
If taking over the settings would give an ad product more than 500 options set as Required Include or Required Exclude, the request fails with 400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED and nothing is deleted.

Campaigns don’t block the deletion. If the option group has no sub-options, campaigns that included it lose that condition. See Effects on Ad Products and Campaigns.

In the console, Delete on a group also deletes its sub-options. Deleting an option group with the API works like Ungroup in the console: its sub-options stay as top-level options.

Request

DELETE /context-targeting/category/{categoryId}

Path Parameters

Parameter	Type	Required	Description
`categoryId`	string	Yes	Option group ID

Example Request

curl -X DELETE https://lake.adrop.io/context-targeting/category/01JAB3XK5SB1C2D3E4F5G6H7J8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

The API returns 200 with the ID of the deleted option group.

{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8"
}

Constraints

Structure

An option group can’t be moved, and an option’s type can’t change after it’s created. To group existing options, create an option group and move the options under it. A new option group can’t be empty, so create it with a Context ID of its own or a new sub-option.
Sub-options created in children count toward the per-request and per-targeting option limits. See Limits.

Own Context IDs are unique among option groups

An option group’s own Context IDs can’t be own Context IDs of another option group in the project, in any context targeting. Regular options and sub-options can share Context IDs with any option.
The rule applies when you create an option group and when you add own Context IDs to an option group with add or set. A conflict fails with 400 TARGETING_COLLECTION_CONTEXT_DUPLICATED, and detail.conflicts lists up to 20 of the conflicting Context IDs with the option groups that already have them. See Error Codes.

An option group can’t become empty

Request	Result
Delete, move, or detach the last sub-option of an option group that has no Context IDs of its own	`400 TARGETING_CATEGORY_NOT_SUPPORTED`. Delete the option group instead; the sub-option moves to the top level.
Remove the last own Context ID of an option group that has no sub-options, with `remove` or `set: []`	`400 TARGETING_CATEGORY_NOT_SUPPORTED`

An option group with its own Context IDs can lose all of its sub-options. It stays as an option group with only its own Context IDs. Option group items per bulk request In one option bulk request, at most 150 items can be option group items. A request with more fails as a whole with 400, and nothing is applied. Split the items and send the requests one after another.

Bulk request	Option group items
Add Options in Bulk	Items that create an option group (`type: "collection"` or `children`), and items with `parent`
Update Options in Bulk	Items with `parent`, including `null`
Delete Options in Bulk	IDs of option groups and sub-options

For a bulk delete, the error code is TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED. detail.limit is the limit, and detail.count is the number of option groups and sub-options in your request.
Renaming an option group, changing its own Context IDs, and setting exposeChildren don’t count as option group items.

Don’t delete an option group and its sub-options in the same bulk request The result depends on their order in ids:

Option group first: The sub-options move to the top level, take over the option group’s settings, and are then deleted as top-level options. Campaigns that included the option group can lose that condition.
Sub-options first: If the option group has no Context IDs of its own, deleting the last sub-option fails with 400 TARGETING_CATEGORY_NOT_SUPPORTED. That option then moves to the top level when the option group is deleted.

​What Is an Option Group

​Create an Option Group

​Request

​Path Parameters

​Request Body

​Example Request

​Example Response

​Add an Option to an Option Group

​Request

​Path Parameters

​Request Body

​Example Request

​Example Response

​Move or Detach an Option

​Request

​Path Parameters

​Request Body

​Example Request

​Example Response

​Show Sub-Options to Advertisers

​Request

​Path Parameters

​Request Body

​Example Request

​Example Response

​Delete an Option Group

​Request

​Path Parameters

​Example Request

​Example Response

​Constraints

What Is an Option Group

Create an Option Group

Request

Path Parameters

Request Body

Example Request

Example Response

Add an Option to an Option Group

Request

Path Parameters

Request Body

Example Request

Example Response

Move or Detach an Option

Request

Path Parameters

Request Body

Example Request

Example Response

Show Sub-Options to Advertisers

Request

Path Parameters

Request Body

Example Request

Example Response

Delete an Option Group

Request

Path Parameters

Example Request

Example Response

Constraints