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

# Add a paused ad to a Meta ad set

`POST /api/v1/tools/meta_add_ad/execute`

## Request

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

Creates one ad, PAUSED, inside an ad set that already exists. The creative is either one that already exists (creative_id) or a new single-image creative built from image_url plus copy.
Use when: the user wants another ad in an ad set — a new creative to test, or the same creative reused in a second audience.
Do not use to create a campaign or an ad set; meta_create_image_campaign and meta_add_ad_set do that.
Do not pass both creative_id and image_url: reusing a creative and making one are different intentions and the tool will not guess.
Returns the new ad id (and the creative id when one was created) and reads the ad back so the paused status is confirmed.
If the user has not said which ad set, ask. Adding an ad to the wrong ad set puts it in front of the wrong audience.

## 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.
    - `ad_set_id` string, required: The ad set the new ad goes into, from meta_list_ad_sets.
    - `ad_name` string, required: Name for the new ad.
    - `creative_id` string: Reuse an existing creative, from meta_get_ad_creatives. Pass exactly one of creative_id, image_url or image_hash.
    - `image_hash` string: An image already in the account library, from meta_list_media (its `image_hash`). Pass this instead of image_url when the file is already in the account — nothing is downloaded or uploaded, so it works for a file that has no public link at all.
    - `image_url` string, uri: The image for a brand-new single-image creative. Requires primary_text and landing_page_url. Adako hosts no files: the platform downloads this URL itself, from its own servers and often hours later, so it must be a public link straight to the file — not a file on the computer, not a Drive, Dropbox or design-tool share page, not a link that expires or asks for a login. Call check_media first: it repairs the usual share links, checks the file against this platform, and says where to put a file that has no link yet.
    - `primary_text` string: Main copy for the new creative. Required with image_url.
    - `headline` string: Headline for the new creative.
    - `description` string: Description line for the new creative.
    - `landing_page_url` string, uri: Where the new creative sends people. Required with image_url.
    - `call_to_action` 'LEARN_MORE' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'DOWNLOAD' | 'BOOK_NOW' | 'GET_QUOTE' | 'CONTACT_US' | 'APPLY_NOW' | 'GET_OFFER' | 'ORDER_NOW' | 'SEE_MORE' | 'GET_STARTED' | 'BUY_NOW' | 'DONATE_NOW' | 'NO_BUTTON': Button label. Defaults to LEARN_MORE.
    - `facebook_page_id` string: Page the new creative runs from, from meta_list_pages.
    - `instagram_account_id` string: Instagram account to run the new creative from.
    - `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)