Search detailed targeting (`adsap_search_detailed_targeting`)

Platform: Meta · Read or write: Read · Plan: All plans · Consumes a task: No · Preview supported: No

What it does

Searches Meta detailed targeting the way the search box in Ads Manager does: interests, behaviors and demographics in one query. Demographics cover job titles, employers, industries, education, life events, parents, relationship status and income. Each result carries a type, the key it goes under inside a flexible_spec group of adsap_create_ad_sets.

When to use it

Use it while planning an ad set, to get the IDs and types for detailed targeting groups.
Put each result under its type inside a group: {"family_statuses": [{"id": "6002714398372", "name": "Parents (All)"}]}. People must match at least one item inside a group, and every group.
Meta runs this search per ad account, so the tool needs ad_account_id and query. It returns 25 results by default and 50 at most.
Meta pads its results with unrelated popular items. Adsap removes those and keeps the results that match your words.
For housing, employment or financial campaigns, pass special_ad_category. Meta then returns approved interests only.
To see how many people the groups reach, pass the same groups to adsap_get_delivery_estimate.

Worked example

You ask

“Find detailed targeting for parents on act_1234567890.”

The assistant calls `adsap_search_detailed_targeting`


{
  "ad_account_id": "act_1234567890",
  "query": "parents",
  "limit": 5
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "ok": true,
  "data": [
    {
      "id": "6002714398372",
      "name": "Parents (All)",
      "type": "family_statuses",
      "path": ["Demographics", "Parents", "All parents", "Parents (All)"],
      "description": "People who are likely to be parents",
      "audience_size_lower": 365496461,
      "audience_size_upper": 429823839
    },
    {
      "id": "6003516132642",
      "name": "Parents (magazine)",
      "type": "interests",
      "path": ["Interests", "Additional interests", "Parents (magazine)"],
      "description": null,
      "audience_size_lower": 54241789,
      "audience_size_upper": 63788344
    }
  ],
  "meta": { "total_count": 5, "query": "parents" }
}

How to read it

type tells you where the item goes: Parents (All) is a demographic under family_statuses, while Parents (magazine) is an interest under interests, so pick by type, not by name. id and name go into the group as they are. audience_size_lower and audience_size_upper are Meta’s worldwide estimate for that one item, not for your ad set.

Some demographic IDs are small numbers, such as 3 for Married under relationship_statuses. Always read an item’s type together with its id. The example shows two of the five results; the other three are the parents by child age groups.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`ad_account_id`	string	Yes	Ad account (act_ prefix). Required: Meta runs this search per ad account.
`query`	string	Yes	Keyword, e.g. “parents”, “nurse”, “yoga”.
`limit`	integer	No
`special_ad_category`	one of `HOUSING`, `EMPLOYMENT`, `CREDIT`, `FINANCIAL_PRODUCTS_SERVICES`, `ISSUES_ELECTIONS_POLITICS`, `ONLINE_GAMBLING_AND_GAMING`	No	The campaign’s Special Ad Category, if it has one. Omit for normal campaigns.

Example prompts

“Find detailed targeting for nurses.”
“Search Meta targeting for people who recently moved.”
“What targeting exists for parents of young children?”

Notes

Meta removed exclusions for detailed targeting in 2025. To leave people out, exclude a custom audience in the ad set instead.

adsap_get_instant_form: Read ONE Meta Instant Form in full: questions, intro, privacy policy and custom disclaimer, thank-you screen, tracking parameters, status…
adsap_list_ads: List ALL ads inside an ad set or a campaign, live from Meta: including ads created today that have no delivery yet (which insights-based…
adsap_manage_instant_form: Create, duplicate, archive or reactivate a Meta Instant Form: the lead form people fill in without leaving Facebook or Instagram.

Guide

Read AI Copilot usage for the workflow around this tool, and the Tool reference for every tool.

Search detailed targeting (adsap_search_detailed_targeting)