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
writeAmazon Adsads.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
In an AI client (MCP)
{
"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>"
}
}From code (Tool API)
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 | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
country_coderequired | string | the Ads profile's 2-letter country code (e.g. 'US'). |
audience_namerequired | string | shown in the Ads console; use a new name for each audience. |
sql_queryrequired | string | AMC SQL over the *_for_audiences tables (sponsored_ads_traffic_for_audiences, conversions_for_audiences, …) whose SELECT returns user_id. |
time_window_startrequired | string · date-time | UTC 'YYYY-MM-DDTHH:MM:SSZ'. |
time_window_endrequired | string · date-time | 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
Every tool answers {notification, data, human_action}; data carries:
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: stringGotchas
- 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.