meta_search_targeting

Search the Meta interests and job titles that an ad set can target.

Ask which interests or job titles an ad set can target. The agent searches Meta by name, so that it targets real options and does not guess an id.

Which interests about yoga can I target on Northwind?

The agent calls meta_search_targeting with interest, or with work_position for a job title. You see each option with its category and the size of its audience, as Meta estimates it. The agent then gives the ids of the options that you choose to meta_create_adset. Meta can rename an option, so the agent keeps the id. Change what runs on Meta shows where this step comes in the job.

Reference

Available on:

Search the Meta interests (type: interest) or job titles (type: work_position) whose name matches q, as this ad account can target them. Returns { id, name, type, path, audienceSizeLowerBound, audienceSizeUpperBound } per option. Give the id of each option that the user chooses in interests or workPositions to meta_create_adset. Keep the id, not the name: Meta can rename an option. Meta gives at most 45 options in one answer. The answer holds at most limit rows (default 100, maximum 500). When it carries nextCursor, more rows exist: call this tool again with the same arguments and cursor set to that value. When it carries no nextCursor, you have every row.

Input

Argument	Type	Required	Description
`advertiserId`	string	yes	Advertiser account ID (`acc_<id>`). Must belong to the active organization — find one with `list_advertisers`.
`q`	string, at least 1 character	yes	The words to search for in the names of the options, for example `yoga`.
`type`	one of `interest`, `work_position`	yes	The type of option to search: `interest`, or `work_position` for a job title.
`cursor`	string, at least 1 character	no	The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor.
`limit`	integer, 1 to 500	no	The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`nextCursor`	string	no	Send this value as `cursor` to get the next page. It is absent on the last page.
`targetingOptions`	array of object	yes	The options whose name matches `q`, in the order of Meta. The list can be empty when `nextCursor` is present.
`targetingOptions[].audienceSizeLowerBound`	integer or null	yes	The lower bound of the audience size that Meta estimates for this option alone. Null when Meta gives none.
`targetingOptions[].audienceSizeUpperBound`	integer or null	yes	The upper bound of the audience size that Meta estimates for this option alone. Null when Meta gives none.
`targetingOptions[].id`	string	yes	The Meta id of the option. Give it in `interests` or `workPositions` to `meta_create_adset`. Keep the id: Meta can rename an option.
`targetingOptions[].name`	string	yes	The name of the option in Meta.
`targetingOptions[].path`	array of string or null	yes	The category of the option and its parent categories, from the top. Null when Meta gives none.
`targetingOptions[].type`	one of `interest`, `work_position`	yes	The type of the option: `interest` or `work_position`.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
provider_not_connected
provider_error
invalid_cursor
organization_unentitled
forbidden
invalid_request
internal_error

Scope

The token must hold observe:read. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Read-only. The tool changes nothing.
Open world. The tool reaches a system outside AdCrunch, such as an ad platform.

Example

The arguments:

{
  "advertiserId": "acc_1485443900032333",
  "limit": 2,
  "q": "yoga",
  "type": "interest"
}

The result, in structuredContent:

{
  "targetingOptions": [
    {
      "audienceSizeLowerBound": 412000000,
      "audienceSizeUpperBound": 484500000,
      "id": "6003139266461",
      "name": "Yoga",
      "path": [
        "Interests",
        "Fitness and wellness",
        "Yoga"
      ],
      "type": "interest"
    },
    {
      "audienceSizeLowerBound": 18400000,
      "audienceSizeUpperBound": 21700000,
      "id": "6003256093937",
      "name": "Hot yoga",
      "path": [
        "Interests",
        "Additional interests",
        "Hot yoga"
      ],
      "type": "interest"
    }
  ]
}