meta_ads_get_delivery_estimate
Get Meta Delivery Estimate (Audience Size)
Description
Estimated audience size from Meta's delivery estimate: the range of monthly active people (audience_size.lower_bound / upper_bound) a targeting setup can reach. Use it to answer "how big is this audience?" before building an ad set, or "how big are my ad sets' audiences?" for existing ones. Two modes: - Account (no adset_ids): sizes a hypothetical audience. optimization_goal and targeting_spec are required; promoted_object is optional (pass it for conversion goals, e.g. {"pixel_id":"…","custom_event_type":"PURCHASE"}). Returns one row. - Ad sets (adset_ids, 1-25, all in account_id): one row per ad set with its name, campaign and effective optimization_goal, sized on its own settings. optimization_goal / targeting_spec / promoted_object, when given, override every ad set's own (a what-if). An ad set from another account fails the call; one ad set Meta cannot estimate gets a row error and the others still return. This is audience size, not a results forecast: Meta deprecated the daily results forecast and daily active people on this endpoint, and the size barely changes with optimization_goal. Never present it as predicted conversions, clicks or reach per day. When estimate_ready is false, say the estimate is provisional. targeting_optimization shows which expansions Meta applies (detailed_targeting, lookalike). Always live, never cached.
Usage
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "meta_ads_get_delivery_estimate",
"arguments": {}
}
}
hopkin meta delivery-estimate get
| Flag | Type | Required | Description |
|---|---|---|---|
--account | string | Required | The ad account ID (with or without act_ prefix). Every ad set in adset_ids must belong to it. |
--adset-ids | array | Optional | Ad sets to size (1-25), one row each, using each ad set's own goal, targeting and promoted object unless overridden below. Omit to size a hypothetical audience at the account level, which then requires optimization_goal and targeting_spec. |
--optimization-goal | string | Optional | Optimization goal. Required without adset_ids; with adset_ids it overrides every ad set's own goal. |
--targeting-spec | object | Optional | Meta targeting spec, passed through unchanged, e.g. {"geo_locations":{"countries":["US"]},"age_min":25,"age_max":44,"flexible_spec":[{"interests":[{"id":"6003139266461"}]}]}. Required without adset_ids; with adset_ids it replaces every ad set's own targeting. |
--promoted-object | object | Optional | Meta promoted object, passed through unchanged, e.g. {"pixel_id":"123","custom_event_type":"PURCHASE"} for OFFSITE_CONVERSIONS. Optional; goals like REACH and LINK_CLICKS work without it. With adset_ids it replaces every ad set's own promoted object. |
--connection-id | string | Optional | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
{
"mcpServers": {
"meta-ads": {
"url": "https://meta.mcp.hopkin.ai",
"transport": "sse"
}
}
}
No example prompts available.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id |
string |
Required | The ad account ID (with or without act_ prefix). Every ad set in adset_ids must belong to it.minLength: 1, maxLength: 40, pattern: ^(act_)?\d+$ |
reason |
string |
Required | Why this tool call is neededminLength: 1, maxLength: 500 |
Optional parameters (5)
| Name | Type | Required | Description |
|---|---|---|---|
adset_ids |
array |
Optional | Ad sets to size (1-25), one row each, using each ad set's own goal, targeting and promoted object unless overridden below. Omit to size a hypothetical audience at the account level, which then requires optimization_goal and targeting_spec. |
optimization_goal |
string |
Optional | Optimization goal. Required without adset_ids; with adset_ids it overrides every ad set's own goal.ADVERTISER_SILOED_VALUE AD_RECALL_LIFT APP_INSTALLS APP_INSTALLS_AND_OFFSITE_CONVERSIONS AUTOMATIC_OBJECTIVE CONVERSATIONS DERIVED_EVENTS ENGAGED_USERS EVENT_RESPONSES IMPRESSIONS IN_APP_VALUE LANDING_PAGE_VIEWS LEAD_GENERATION LINK_CLICKS MEANINGFUL_CALL_ATTEMPT MESSAGING_APPOINTMENT_CONVERSION MESSAGING_PURCHASE_CONVERSION NONE OFFSITE_CONVERSIONS PAGE_LIKES POST_ENGAGEMENT PROFILE_AND_PAGE_ENGAGEMENT PROFILE_VISIT QUALITY_CALL QUALITY_LEAD REACH REMINDERS_SET SUBSCRIBERS THRUPLAY VALUE VISIT_INSTAGRAM_PROFILE |
targeting_spec |
object |
Optional | Meta targeting spec, passed through unchanged, e.g. {"geo_locations":{"countries":["US"]},"age_min":25,"age_max":44,"flexible_spec":[{"interests":[{"id":"6003139266461"}]}]}. Required without adset_ids; with adset_ids it replaces every ad set's own targeting. |
promoted_object |
object |
Optional | Meta promoted object, passed through unchanged, e.g. {"pixel_id":"123","custom_event_type":"PURCHASE"} for OFFSITE_CONVERSIONS. Optional; goals like REACH and LINK_CLICKS work without it. With adset_ids it replaces every ad set's own promoted object. |
connection_id |
string |
Optional | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |