---
title: "Add a paused ad set to a Meta campaign"
method: POST
path: "/api/v1/tools/meta_add_ad_set/execute"
tags: ["Meta Ads"]
---

# Add a paused ad set to a Meta campaign

`POST /api/v1/tools/meta_add_ad_set/execute`

## Request

- Base URL: `https://adako.ai`
- URL: `https://adako.ai/api/v1/tools/meta_add_ad_set/execute`
- Auth: HTTP bearer

Creates one new ad set, PAUSED, inside a campaign that already exists: its own audience, optimisation goal, budget and schedule. It does not create any ads — add one afterwards with meta_add_ad.
Use when: the user wants to test another audience, another geography or another optimisation goal inside the same campaign.
Do not use when the campaign holds the budget (campaign budget optimisation): the new ad set must not carry its own budget, and Meta rejects it. The preview says so before anything is sent.
Do not pass free text for locations or interests; use meta_search_targeting first.
Returns the new ad set id and reads it back so the paused status and budget are confirmed.
The preview refuses what Meta would reject: unknown location keys, EU/EEA targeting without dsa_beneficiary and dsa_payor, a budget below Meta's minimum, past dates, and targeting the campaign's special ad category forbids.
If the user has not said what the new ad set should target differently, ask — a duplicate of an existing ad set just splits the same budget.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `arguments` object, required
    - `ad_account_id` string: Meta ad account id such as act_1234567890. Omit it to use the primary account; if several accounts are active and none is primary the call fails and lists the valid ids.
    - `campaign_id` string, required: The campaign the new ad set belongs to, from meta_list_campaigns.
    - `ad_set_name` string, required: Name for the new ad set.
    - `daily_budget` number: Daily budget as a decimal in the account currency (25 means 25 dollars, not 2500 cents). One of daily_budget or lifetime_budget is required.
    - `lifetime_budget` number: Total budget for the whole flight, decimal in the account currency. Requires end_time.
    - `budget_level` 'ad_set' | 'campaign': Which level holds the budget. "ad_set" (the default) gives this ad set its own budget, so every ad set is funded separately. "campaign" is Meta's campaign budget optimisation (Advantage campaign budget): the campaign holds one budget and Meta decides how much each ad set gets — ad sets added later must then carry no budget of their own. Only "campaign" can be edited with meta_update_campaign_budget.
    - `start_time` string: When delivery may start: YYYY-MM-DD (00:00 in the ad account's time zone) or an ISO timestamp with a UTC offset, e.g. 2026-10-01T09:00:00+02:00. Not in the past; today or omitted means as soon as the user activates it.
    - `end_time` string: When delivery must stop: YYYY-MM-DD (runs to 23:59:59 in the ad account's time zone) or an ISO timestamp with a UTC offset. Required with lifetime_budget.
    - `optimization_goal` string: Override what the ad set optimises for. Leave empty to use the objective default. LEAD_GENERATION (instant forms) is not supported; PAGE_LIKES promotes the Page.
    - `billing_event` string: What Meta charges for. Leave empty to use IMPRESSIONS.
    - `countries` string[]: ISO 3166-1 two-letter country codes from meta_search_targeting: GB, not UK; GR, not EL.
    - `region_keys` string[]: Region keys from meta_search_targeting (never region names). Checked with Meta first.
    - `city_keys` string[]: City keys from meta_search_targeting (never city names, postcodes or media markets). Each city is targeted with a 25 km radius.
    - `age_min` integer: Youngest age to target. Minimum 18.
    - `age_max` integer: Oldest age to target. 65 means 65 and over.
    - `genders` 'all' | 'men' | 'women': Restrict by gender. Defaults to all — narrow only when the user asks.
    - `interest_ids` string[]: Interest ids from meta_search_targeting or meta_browse_targeting. Never free text.
    - `behavior_ids` string[]: Behaviour ids from meta_search_targeting or meta_browse_targeting. Never free text.
    - `custom_audience_ids` string[]: Custom audience ids from meta_list_custom_audiences.
    - `excluded_custom_audience_ids` string[]: Custom audiences to exclude, e.g. existing customers.
    - `advantage_audience` boolean: Let Meta deliver beyond the listed interests. Defaults to off so the targeting the user asked for is the targeting they get.
    - `dsa_beneficiary` string: Who benefits from the ad. Required whenever the targeting reaches the EU or EEA — a country, or a region or city inside one, including territories such as Réunion.
    - `dsa_payor` string: Who pays for the ad. Required whenever the targeting reaches the EU or EEA — a country, or a region or city inside one.
    - `objective` 'OUTCOME_AWARENESS' | 'OUTCOME_TRAFFIC' | 'OUTCOME_ENGAGEMENT' | 'OUTCOME_LEADS' | 'OUTCOME_SALES' | 'OUTCOME_APP_PROMOTION': Only needed when the campaign uses a legacy objective Meta no longer accepts on create. Normally leave empty: the campaign decides.
    - `pixel_id` string: Pixel for a conversion-optimised ad set; from meta_list_pixels.
    - `facebook_page_id` string: The Page a PAGE_LIKES ad set promotes, from meta_list_pages. Only used with optimization_goal PAGE_LIKES; required when the account has several Pages.
    - `dynamic_creative` boolean: Make this a dynamic creative ad set, which Meta requires before meta_create_flexible_ad can put an asset-feed ad in it. Meta allows exactly one ad in such an ad set, so leave it off unless the plan is a flexible ad.
    - `idempotency_key` string: Optional caller-supplied key; identical keys never execute twice.
    - `raw_data` boolean: Return compact JSON only (no markdown). Use when you will compute on the result.

## Response `200`

The tool ran. A write returns proposal_id and approve_url while the change waits for approval.

- SuccessEnvelope
  - `success` unknown, required
  - `tool` string, required
  - `data` object, required: Machine-readable result.
  - `markdown` string, required: The same result written for a person or a model.
  - `quota` Quota: Task usage for the current billing period.
    - `plan` string
    - `used` integer
    - `limit` integer
    - `period_end` string
    - `upgrade_url` string
  - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved.
  - `approve_url` string: Where a person approves the proposal.
  - `request_id` string, required

## Other responses

- `400`: Invalid arguments, or the ad account could not be resolved.
- `401`: Missing, invalid, revoked or expired API key.
- `402`: Monthly task quota used up, or the plan does not include this tool.
- `403`: The connected ad account lacks the access level this tool needs.
- `404`: Unknown tool name.
- `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments.
- `429`: Rate limited by Adako or by the ad platform. See Retry-After.
- `500`: Unexpected error inside Adako.
- `502`: The ad platform returned an error.

---

[API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)