# ads_create_query_based_audience (https://sellersheetai.com/docs/mcp-api/tools/ads_create_query_based_audience)

> Create an AMC rule-based audience: the shoppers an AMC query selects become an audience in the store's sponsored-ads account — a Sponsored Products / Brands bid adjustment (bidAdju

Access: **WRITE** · toolset amazon_ads · family ads.amc-audiences

stments.audienceBidAdjustments in ads_update_campaign) or a Sponsored Display target. Ask the seller first: an audience cannot be edited once created. Amazon Ads API · createQueryBasedAudience · POST /amc/audiences/query Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/createQueryBasedAudience Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.

## Call it

MCP tool call:

```json
{
  "name": "ads_create_query_based_audience",
  "arguments": {
    "store": "myStore-US",
    "country_code": "<country_code>",
    "audience_name": "<audience_name>",
    "sql_query": "<sql_query>",
    "time_window_start": "<time_window_start>",
    "time_window_end": "<time_window_end>"
  }
}
```

Tool API (early access — contact us):

```bash
curl -X POST https://api.sellersheetai.com/api/v1/tools/ads_create_query_based_audience \
  -H "Authorization: Bearer $SELLERSHEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store":"myStore-US","country_code":"<country_code>","audience_name":"<audience_name>","sql_query":"<sql_query>","time_window_start":"<time_window_start>","time_window_end":"<time_window_end>"}'
```

## Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `store` | string | yes | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
| `country_code` | string | yes | the Ads profile's 2-letter country code (e.g. 'US'). |
| `audience_name` | string | yes | shown in the Ads console; use a new name for each audience. |
| `sql_query` | string | yes | AMC SQL over the *_for_audiences tables (sponsored_ads_traffic_for_audiences, conversions_for_audiences, …) whose SELECT returns user_id. |
| `time_window_start` | string · date-time | yes | UTC 'YYYY-MM-DDTHH:MM:SSZ'. |
| `time_window_end` | string · date-time | yes | UTC 'YYYY-MM-DDTHH:MM:SSZ'. |
| `audience_description` | string |  | optional text shown with the audience. |
| `time_window_relative` | boolean |  | true to move the window forward at each refresh (recent shoppers). |
| `parameter_values` | object |  | values for parameters the SQL declares. |

## Result

- `data.audience_execution_id` — poll it with ads_get_query_based_audience_by_audience_execution_id.
- `data.status` — PENDING at first.

## Body (Amazon schema)

- advertiserId*: string audienceDescription: string audienceName*: string countryCode: AE | AU | BR | CA | DE | ES | FR | IN | IT | JP | MX | NL | SA | SE | TR | UK | US inputParameters: [{columnType: DIMENSION | METRIC, dataType*: string | {elementDataType, elementNullable, type} | {precision, type} | {keyDataType, type, valueDataType, valueNullable} | {fields, type}, defaultValue, description, name*}] (max 100) inputParameters.dataType.type: ARRAY | DECIMAL | MAP | STRUCT parameterValues: object query: string refreshRateDays: integer (0–21; default 21) timeWindowEnd*: string (date-time) timeWindowRelative: boolean (default False) timeWindowStart*: string (date-time) workflowId: string

## Gotchas

- Gate: commit — the audience goes to the seller's ads account and cannot be changed.
- The advertiser is the store's AMC instance's own; it is not a parameter.
- Amazon refreshes the audience itself; one left unused in campaigns is refreshed less often and deactivated after about 100 days.

## Workflow

- 1. Count the shoppers first with ads_create_workflow_execution (SELECT COUNT(DISTINCT user_id) … over the same tables without _for_audiences); Amazon fails an audience under 2,000 (aim for 2,500). 2. Create it here; poll ads_get_query_based_audience_by_audience_execution_id. 3. When it SUCCEEDED, find its audienceId with ads_list_targetable_entities.