---
search:
  tags:
    - Ad groups
    - POST
seo:
  description: >-
    Available on: Meta. Reference for the POST
    /mutations/{advertiserId}/ad-groups endpoint in the AdCrunch API.
sidebar:
  label: Create an ad group
  badge: POST
title: Create an ad group
type: openapi-operation
---
**Available on:** [![Meta](/providers/meta.svg)](https://docs.adcrunch.dev/connect/providers)

Creates an ad group. The body holds the fields of the new ad group.

It starts a Mutation of the kind `meta_create_adset`, the same change that `POST /mutations` starts with that kind. The MCP tool of the same name makes the same change.

The change does **not** happen during this request. The answer is `202`, and `Location` names the Mutation. Poll `GET /mutations/{id}` until it reports `complete` or `errored`. A Mutation is durable, so the id stays valid across retries and restarts.

A refused request starts nothing. AdCrunch refuses a body that does not match, an advertiser that is not yours, an advertiser with no usable connection, and an advertiser connected without write access before a Mutation exists. So a failed call leaves no row in the history.

**This operation checks the credential first and the body second.** A missing or unusable credential answers `401` even when the body is wrong as well.

A create and a copy never start delivery: the new object arrives **paused**. Send `PATCH …/status` with `ACTIVE` to start it.

`POST /mutations/{advertiserId}/ad-groups`

**Request body** (`application/json`, required)

- `advantageAudience` (boolean, required) — Whether Meta can show the ads to people outside the targeting (Advantage+ audience). This field is required. It has no default. With true, Meta uses the gender, the interests, the job titles and the included Custom Audiences as a suggestion. Meta can then deliver to other genders and to older people when it expects better results. The countries and the minimum age stay hard limits. With true, ageMin must be 25 or less. With true, Meta fixes the oldest age at 65, so ageMax is not allowed. With false, Meta delivers only to the targeting. Ask the user when you do not know.
- `ageMax` (integer) — The oldest age to target, from 13 to 65. Omit it to target every age above the minimum. 65 and above is one group on Meta. Omit it when advantageAudience is true.
- `bidCap` (number) — The highest bid Meta places in an auction. Only with LOWEST\_COST\_WITH\_BID\_CAP. A bid is per optimization event, for example per purchase, and per 1,000 impressions when the optimization goal is IMPRESSIONS or REACH. The amount is in whole units of the ad account currency: 2.5 is 2.50. Meta refuses more decimals than the currency has.
- `costCap` (number) — The average cost per result that Meta tries to keep. Only with COST\_CAP. A bid is per optimization event, for example per purchase, and per 1,000 impressions when the optimization goal is IMPRESSIONS or REACH. The amount is in whole units of the ad account currency: 2.5 is 2.50. Meta refuses more decimals than the currency has. A cost cap can stop the ad set before it spends its full budget.
- `roasFloor` (number) — The lowest return on ad spend that Meta bids for, as a ratio: 1.5 means purchase value of 1.5 times the spend. Only with LOWEST\_COST\_WITH\_MIN\_ROAS. From 0.01 to 1000, with at most 4 decimals.
- `bidStrategy` (string) — How Meta bids. LOWEST\_COST\_WITHOUT\_CAP ("Highest volume" in Ads Manager) gets the most results for the budget and takes no amount. LOWEST\_COST\_WITH\_BID\_CAP ("Bid cap") takes bidCap. COST\_CAP ("Cost per result goal") takes costCap. LOWEST\_COST\_WITH\_MIN\_ROAS ("ROAS goal") takes roasFloor, and needs the optimization goal VALUE. Give exactly the amount that the strategy takes, and no other amount. A higher bid cap, a higher cost cap or a lower ROAS floor can make an ad set spend its full budget, never more. When the campaign carries the budget, or shares the ad set budgets, the campaign holds the strategy. Then give the same bidStrategy here, with the amount for this ad set. When the strategy of the campaign takes no amount, you can omit both. Otherwise the ad set holds the strategy. When you omit it there, AdCrunch sends LOWEST\_COST\_WITHOUT\_CAP.
- `ageMin` (integer, required) — The youngest age to target, from 13 to 65. This field is required, and it is the one targeting field with no default. Many advertisers must not show ads to people under 18, and a default would spend their money on an audience they cannot legally address. State the age deliberately: send 18 to exclude minors.
- `campaignId` (string, required) — The Meta id of the campaign this ad set belongs to, digits only. Create the campaign first and use the id it returns.
- `countries` (string[], required) — The countries to target, as two-letter ISO 3166-1 alpha-2 codes, for example US or GB. Give at least one.
- `customAudiences` (string[]) — The Meta ids of the Custom Audiences to target, digits only. Meta then delivers only to people in one of these audiences or more. With interests or job titles too, a person must also match one of them. Find them with the Custom Audiences read of AdCrunch, and choose ones that are usable. With advantageAudience true, Meta uses these audiences as a suggestion.
- `excludedCustomAudiences` (string[]) — The Meta ids of the Custom Audiences to exclude, digits only. Meta does not deliver to a person in one of these audiences, also with advantageAudience true. For example, exclude your customers from an ad set that finds new ones. Find them with the Custom Audiences read of AdCrunch.
- `interests` (string[]) — The Meta ids of the interests to target, digits only. Find them with the targeting search of AdCrunch, with type interest. Send the id, not the name: Meta can rename an interest. The interests and the workPositions make one group. Meta delivers to a person who matches one of them or more. No interest can be excluded. With advantageAudience true, Meta uses the group as a suggestion. Meta refuses an interest that it removed or merged, in its own words.
- `workPositions` (string[]) — The Meta ids of the job titles to target, digits only. Find them with the targeting search of AdCrunch, with type work\_position. Send the id, not the name: Meta can rename a job title. The job titles and the interests make one group. Meta delivers to a person who matches one of them or more. With advantageAudience true, Meta uses the group as a suggestion.
- `customConversionId` (string) — The Meta id of the custom conversion to optimize for, digits only. Find it with the custom conversions read of AdCrunch, and choose one that is usable. Send it in place of customEventType, with the pixelId of the custom conversion. The custom conversion gives the event, so do not send customEventType with it.
- `customEventType` (string) — The conversion the pixel reports, for example PURCHASE. A conversion optimization goal needs pixelId, with customEventType or customConversionId.
- `dailyBudget` (number) — The amount this ad set spends each day. The amount is in whole units of the ad account currency: 10.5 is 10.50. Meta refuses more decimals than the currency has, and it counts some currencies, such as JPY and HUF, with none. Omit both budgets when the campaign carries one. When the campaign carries none, give exactly one.
- `endTime` (string) — When delivery stops, as an ISO 8601 timestamp. Required with a lifetime budget.
- `genders` (string, required) — Which genders to target. The default targets everybody.
- `lifetimeBudget` (number) — The amount this ad set spends across its whole schedule. The amount is in whole units of the ad account currency: 10.5 is 10.50. Meta refuses more decimals than the currency has, and it counts some currencies, such as JPY and HUF, with none. It needs an end time.
- `name` (string, required) — The ad set name. It is visible in Meta Ads Manager.
- `optimizationGoal` (string, required) — What Meta optimizes delivery for. The campaign objective limits which goals are valid. A conversion goal also needs pixelId, with customEventType or customConversionId. The billing event follows from this goal, so there is no separate field for it.
- `pixelId` (string) — The Meta pixel that reports conversions. Required with a conversion optimization goal. AdCrunch can list the pixels this ad account can use.
- `startTime` (string) — When delivery starts, as an ISO 8601 timestamp. Omit it to start when the ad set becomes active. The ad set is created paused either way.

Request body example:

```json
{
  "advantageAudience": false,
  "ageMin": 18,
  "campaignId": "120210000000000",
  "countries": [
    "US"
  ],
  "dailyBudget": 20,
  "name": "Spring sale - US",
  "optimizationGoal": "LINK_CLICKS"
}
```

**Responses**

- `202` — The Mutation started, and it has not ended. The body is the answer of \`GET /mutations/{id}\`, with \`status\` of \`running\`. Poll the path in \`Location\` for the outcome.
- `400` — The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. \`error\` is \`invalid\_request\`, and \`issues\` names each field. Nothing was changed.
- `401` — No API key, or one that does not resolve. See the security scheme. \`error\` is \`unauthorized\`.
- `402` — The organization has no active subscription. An owner subscribes at \`paywallUrl\`. \`error\` is \`organization\_unentitled\`.
- `403` — The caller does not hold \`mutation:write\`, or the advertiser is connected without write access. In the second case \`error\` is \`missing\_write\_access\` and \`message\` says how to fix it. AdCrunch started nothing.
- `404` — The advertiser does not exist, it belongs to another organization, or it is not a Meta ad account. \`error\` is \`not\_found\` in each case. An advertiser that does not exist and an advertiser of another organization get the same answer on purpose, so a caller cannot learn which ids exist. AdCrunch started nothing.
- `409` — The advertiser has no usable connection: a person removed it, it expired, or the provider refused it. A person must connect it again. \`error\` is \`provider\_not\_connected\`, the code that a live read of Observe sends for the same failure. AdCrunch started nothing.

Response example, 202:

```json
{
  "mutationId": "mut_k3x9q2v7m4n8p1r5t6w0y2z4",
  "status": "running"
}
```
