Advertising
36 tools for campaign analytics, bid management, keyword state changes, portfolio rollups, keyword metrics, SQP ads coverage evidence, brand metrics, attribution, DSP reporting, Brand Store insights, audience discovery, audience bid adjustments, and competitive intelligence.
get_campaign_performanceReadGet campaign-level performance metrics (spend, ACOS, ROAS, CTR, etc.) over a date range. Use this to analyze overall campaign health and compare campaigns.
When to use
Inspect overall ad spend efficiency, campaign comparisons, and campaign-level performance outliers.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
sort_by | enum (spend) | Column to sort by. Options: spend, sales, acos, roas, ctr, cpc, cvr, impressions, clicks, orders, units_sold, campaign_name. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by ACOS descending to list campaigns with the highest ad cost of sales first.
- Use campaign_name with % wildcards to filter by your naming convention (e.g. "SP-Exact%").
- Compare 30-day windows rather than 7-day windows, because the 14-day attribution window makes short periods unreliable.
- Use profile_id to isolate a specific advertising profile. Agent Central provisions United States profiles at launch.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
get_campaign_historyReadGet daily Sponsored Products campaign settings snapshots, including state, budget, bidding strategy, and placement bid adjustments.
When to use
Use this when you need to see how a campaign was configured on prior days, separate from performance metrics.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Snapshot start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | Snapshot end date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_id | string | Filter by campaign ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
state | enum | Filter by campaign state: ENABLED, PAUSED, or ARCHIVED. |
sort_by | enum (snapshot_date) | Column to sort by: snapshot_date, campaign_name, campaign_id, state, or budget_amount. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Filter by campaign_id when auditing a single campaign after a budget or state change.
- Sort ascending to read a campaign timeline from oldest to newest.
- Use this alongside get_campaign_performance to separate configuration changes from market or attribution changes.
Watch out
- Campaign history is based on daily snapshots, so same-day changes are visible after the next campaign snapshot sync.
get_campaign_changesReadFind Sponsored Products campaign setting changes between daily snapshots, including state, budget, bidding strategy, portfolio, and placement bid modifier changes.
When to use
Use this after performance moves, or after an agent/user write action, to identify which campaign settings changed in the same period.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Change window start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | Change window end date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_id | string | Filter by campaign ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
change_types | array | Optional change types: state, budget, bidding_strategy, top_of_search_bid_adjustment, product_page_bid_adjustment, rest_of_search_bid_adjustment, portfolio. |
sort_order | enum (desc) | Sort direction by snapshot date: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Filter change_types to budget and state when reviewing spend changes.
- Use campaign_name with naming wildcards to audit a campaign family.
- Pair with diagnose_performance to connect setting changes to metric movement.
Watch out
- Changes are detected between daily snapshots, not as a real-time event stream.
get_adgroup_performanceReadGet ad group-level performance metrics. Use this to drill into campaign performance by ad group.
When to use
Drill into a specific campaign to understand which ad groups are driving spend and which are converting well.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
ad_group_name | string | Filter by ad group name (LIKE match). |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name and ad_group_name. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Filter by campaign_name first, then sort by ACOS to find the worst-performing ad groups within a campaign.
- Compare ad group performance across campaigns to find where the same product performs best.
- Use ad_group_name filter with wildcards to target groups by naming pattern.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
get_keyword_performanceReadGet keyword/target-level performance metrics for bidded Sponsored Products targets.
When to use
Inspect individual keyword bids, ACOS, ROAS, spend, sales, and impression share.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
keyword | string | Filter by keyword text (LIKE match). |
keyword_type | enum | Filter by keyword type: BROAD, PHRASE, EXACT, TARGETING_EXPRESSION, or TARGETING_EXPRESSION_PREDEFINED. |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name, keyword, keyword_type, match_type. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by spend descending to list highest-spend keywords first, then compare ACOS and ROAS.
- Filter by keyword_type=EXACT to focus on your most intentional targeting.
- Look at top_of_search_impression_share to gauge bid competitiveness.
- Use the keyword filter with wildcards to find all variations of a root keyword.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
get_placement_breakdownReadGet performance broken down by ad placement (Top of Search, Detail Page, Other, Off Amazon).
When to use
Compare spend, sales, ACOS, ROAS, CTR, and CVR across ad placements.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name and placement_classification. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Compare ACOS between Top of Search and Rest of Search placement rows.
- Product Page placements often have lower CTR but can have good CVR for complementary products.
- Use update_campaign_bidding separately when the caller has selected placement adjustment values.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
get_product_performanceReadGet per-SKU/ASIN advertising performance. Use this to see which products are being advertised and how they perform.
When to use
Check how much you are spending on advertising each product and whether the ad spend is converting into profitable sales.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
asin | string | Filter by advertised ASIN (exact match). |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name, advertised_asin, advertised_sku. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by spend descending to find your highest-cost advertised products, then check ACOS and same_sku_sales.
- Compare same_sku_sales vs total sales to see how much cross-sell attribution is happening.
- Filter by a specific ASIN to see all campaigns and ad groups advertising that product.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
Related tools
get_purchased_productsReadGet purchase attribution data showing what customers actually bought after clicking an ad.
When to use
Discover which products customers are buying after clicking ads for a different product, and identify cross-sell or halo effects.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
advertised_asin | string | Filter by advertised ASIN (exact match). |
purchased_asin | string | Filter by purchased ASIN (exact match). |
sort_by | enum (sales) | Column to sort by: sales, orders, units_sold, campaign_name, purchased_asin, advertised_asin. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Filter by advertised_asin to see all products that customers bought after clicking ads for that ASIN.
- Look for cases where purchased_asin differs from advertised_asin to identify cross-sell attribution patterns.
- This data only contains sales attribution. There is no click, impression, or cost data here.
Watch out
- This table has no click, impression, or cost data. It only contains sales attribution.
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales.
Related tools
get_search_termsReadGet search term performance data. Shows which customer search terms triggered your ads and their performance.
When to use
Inspect converting search terms, non-converting spend, matched keyword text, match type, and ad-attributed metrics.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
search_term | string | Filter by search term (LIKE match). |
match_type | enum | Filter by match type: BROAD, PHRASE, or EXACT. |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name, search_term, keyword, match_type. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by spend descending with a high limit to find search terms burning budget without converting.
- Filter for search terms with high clicks and zero sales when reviewing non-converting traffic.
- Filter by match_type=BROAD to find the search terms that broad match is matching to.
- Use match_type and keyword columns to distinguish source targeting from the customer search term.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete sales and ACOS.
get_sales_and_trafficReadGet total sales and traffic metrics from Business Reports (organic + PPC combined). Includes sessions, page views, units ordered, revenue, conversion rate, and buy box percentage by ASIN/SKU.
When to use
Get the full picture of product performance including organic and paid traffic combined, or check conversion rates and Buy Box percentages.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
asin | string | Filter by ASIN (exact match). |
sku | string | Filter by SKU (exact match). |
sort_by | enum (total_sales) | Column to sort by: total_sales, units_ordered, sessions, page_views, avg_conversion_rate, avg_buy_box_pct. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Compare avg_conversion_rate across ASINs to list products by conversion-rate differences.
- Low avg_buy_box_pct indicates competitive pressure or pricing issues.
- Use this alongside get_campaign_performance to see how ad spend relates to total sales.
Watch out
- Business Reports have a ~72 hour delay. For near-real-time revenue, use get_todays_sales.
Related tools
get_tacosReadCalculate TACOS (Total ACOS) and PPC percentage by joining SP + SD ad spend with total sales from Business Reports. TACOS = total ad spend / total sales. PPC % = ad sales / total sales.
When to use
Evaluate the true advertising efficiency at the ASIN level by comparing ad spend against total revenue, not just ad-attributed revenue.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
asin | string | Filter by ASIN (exact match). |
sort_by | enum (total_sales) | Column to sort by: total_sales, ad_spend, ad_sales, organic_sales, tacos, ppc_pct, acos, total_units, sessions. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- TACOS below 10% is healthy for most categories. Above 15% warrants investigation.
- High ppc_pct (above 50%) means you are heavily dependent on advertising for sales.
- Sort by organic_sales to find products that sell well without heavy ad support.
- Compare TACOS trends over time to track progress toward organic ranking.
Watch out
- SB (Sponsored Brands) spend is not included because it lacks per-ASIN attribution.
- Business Reports have a ~72 hour delay, so TACOS for recent days will be incomplete.
get_search_query_performanceReadGet Brand Analytics Search Query Performance (SQP) data. Shows search query volume, market-level funnel metrics, and your ASIN share at each stage. Computes Brand CR vs Market CR.
When to use
Inspect search volume, market share, and conversion-rate comparisons for search queries and ASINs.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date for week range (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date for week range (YYYY-MM-DD). Defaults to today. |
asin | string | Filter by ASIN (exact match). |
search_query | string | Filter by search query (LIKE match, use % for wildcards). |
min_volume | number | Minimum search query volume. |
sort_by | enum (search_query_volume) | Column to sort by. Options include search_query_volume, search_query, market_cr, brand_cr, cr_delta, and all share metrics. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by cr_delta descending to list keywords where your conversion rate is above the market rate.
- Use min_volume to filter out long-tail keywords and keep higher-traffic query rows.
- Compare asin_impression_share_pct vs asin_purchase_share_pct to find keywords where you convert above your visibility share.
- Positive cr_delta means your brand converts better than the market for that query.
Watch out
- SQP data is weekly granularity. Dates align to Sunday-through-Saturday weeks, not arbitrary ranges.
get_search_query_ad_coverageReadGet SQP search query rows joined to observed Sponsored Products search-term and keyword-target coverage evidence.
When to use
Inspect whether SQP query rows have observed paid search-term evidence or matching configured keyword targets, with campaign and ad group locations.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date for SQP week range (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date for SQP week range (YYYY-MM-DD). Defaults to today. |
asin | string | Filter by SQP ASIN (exact match). |
search_query | string | Filter by SQP search query (LIKE match, use % for wildcards). |
coverage_state | enum | Filter by deterministic coverage state: exact_keyword_active, phrase_or_broad_keyword_active, auto_or_targeting_search_term_seen, search_term_seen_no_keyword_match, no_paid_coverage_observed, or data_gap. |
profile_id | string | Filter ads evidence by profile ID. |
campaign_id | string | Filter ads evidence by Sponsored Products campaign ID. |
ad_group_id | string | Filter ads evidence by Sponsored Products ad group ID. |
min_volume | number | Minimum SQP search query volume. |
sort_by | enum (search_query_volume) | Column to sort by. Options include search_query_volume, paid_spend, paid_clicks, paid_sales, matching_keyword_count, matching_search_term_count, active_campaign_count, coverage_state, market_cr, brand_cr, and share metrics. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
Tips
- Coverage matching uses normalized text equality only: case and whitespace are normalized; punctuation, stemming, and singular/plural variants are not collapsed.
- paid_spend, paid_clicks, paid_sales, and paid_orders come from matching ads search-term rows where the observed customer search term equals the normalized SQP query.
- keyword_evidence rows show configured keyword/target matches and keyword state separately from observed search-term metrics.
- advertised_asin_match_method identifies the campaign/ad-group advertised-product map used to connect ads evidence to the SQP ASIN.
Watch out
- Broad or phrase keyword coverage is configured coverage evidence, not proof that every exact SQP query variation will trigger.
- A data_gap state means no ads search-term or keyword rows were observed for the selected ads scope and SQP week.
get_brand_healthReadGet Amazon Ads Brand Metrics health by brand and category. Includes awareness, consideration, sales, engaged-shopper rate, conversion rate, and new-to-brand rate versus category peers.
When to use
Use this to understand whether a brand is gaining category awareness, converting consideration into purchases, and acquiring new-to-brand customers compared with category peers.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (90 days ago) | Metric computation start date (YYYY-MM-DD). Defaults to 90 days ago. |
end_date | string (today) | Metric computation end date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
brand_name | string | Filter by brand name (LIKE match, use % for wildcards). |
category_tree_name | string | Filter by category tree name. |
category_path | string | Filter by category path (LIKE match, use % for wildcards). |
sort_by | enum (metrics_computation_date) | Column to sort by: metrics_computation_date, brand_name, category_path, awareness_index, consideration_index, sales_index, engaged_shopper_rate_midpoint, customer_conversion_rate, customer_conversion_rate_vs_median, new_to_brand_customer_rate, new_to_brand_customer_rate_vs_median. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Compare customer_conversion_rate_vs_median to see where the brand converts better or worse than category peers.
- Use category_path with wildcards to isolate a category family.
- Track awareness_index, consideration_index, and sales_index over weekly computation dates.
Watch out
- Brand Metrics requires Amazon Ads Brand Metrics availability for the advertiser and category, so some profiles may return no rows.
get_attribution_performanceReadGet Amazon Attribution performance for off-Amazon channels, including publisher, campaign, ad group, creative, product, purchases, units, sales, brand halo, and new-to-brand metrics.
When to use
Use this to measure how non-Amazon channels such as Google Ads, Facebook, Microsoft Ads, publishers, and creators drive shopping actions on Amazon through Attribution tags.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (yesterday) | End date (YYYY-MM-DD). Defaults to yesterday. |
profile_id | string | Filter by ad account profile ID. |
report_type | enum (PERFORMANCE) | PERFORMANCE, PRODUCTS, or ALL. |
publisher | string | Filter by off-Amazon publisher (LIKE match, use % for wildcards). |
campaign_id | string | Filter by Attribution campaign ID. |
ad_group_id | string | Filter by Attribution ad group ID. |
creative_id | string | Filter by Attribution creative ID. |
product_asin | string | Filter product-report rows by purchased ASIN. |
product_conversion_type | string | Filter product-report rows by conversion type. |
min_sales | number | Only include rows with at least this 14-day attributed sales value. |
sort_by | enum (attributed_sales_14d) | Column to sort by: date, publisher, campaign_id, ad_group_id, creative_id, attributed_sales_14d, attributed_purchases_14d, attributed_total_purchases_14d, total_attributed_sales_14d, click_throughs, detail_page_view_rate, or purchase_rate. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Filter publisher to compare paid social, search, creator, and affiliate traffic.
- Use report_type=PRODUCTS when you need ASIN-level brand halo and new-to-brand attribution.
- Sort by purchase_rate to find efficient off-Amazon traffic sources, not just high-volume channels.
Watch out
- Amazon Attribution requires Attribution setup and eligible advertiser access. Profiles without Attribution advertisers can have no rows even when regular ads reporting works.
get_sb_campaign_performanceReadGet Sponsored Brands campaign performance. Includes new-to-brand metrics, branded searches, video views, and detail page views.
When to use
Evaluate Sponsored Brands campaigns for brand awareness impact, new customer acquisition, and video engagement.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name, ntb_orders, ntb_sales, branded_searches, dpv, video_completes. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Track ntb_orders (new-to-brand orders) to measure customer acquisition, not just revenue.
- branded_searches indicates how much brand awareness the campaign is driving.
- video_completes helps evaluate whether video creative is engaging enough.
Watch out
- SB campaigns lack per-ASIN attribution, so they are excluded from TACOS calculations.
- Ads data has a 3-day attribution lag. Recent days will show incomplete metrics.
get_sd_campaign_performanceReadGet Sponsored Display campaign performance. Includes viewability, new-to-brand metrics, and detail page views.
When to use
Evaluate Sponsored Display campaigns for retargeting effectiveness, viewability, and new customer reach.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus campaign_name, ntb_orders, ntb_sales, dpv, avg_viewability. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Low avg_viewability (below 40%) suggests your display placements are below the fold or in poor positions.
- Compare dpv (detail page views) against clicks to measure product page engagement.
- SD data is included in TACOS calculations, unlike SB data.
Watch out
- Ads data has a 3-day attribution lag. Recent days will show incomplete metrics.
get_dsp_performanceReadGet Amazon DSP order, line item, and creative performance from Reporting v3 offline reports, including spend, sales, ROAS, viewability, and video completion metrics.
When to use
Use this to evaluate programmatic display and video campaigns at the order, line item, and creative level.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (yesterday) | End date (YYYY-MM-DD). Defaults to yesterday. |
dsp_advertiser_id | string | Filter by DSP advertiser ID. |
order_name | string | Filter by DSP order name (LIKE match, use % for wildcards). |
line_item_name | string | Filter by DSP line item name (LIKE match, use % for wildcards). |
creative_name | string | Filter by creative name (LIKE match, use % for wildcards). |
min_spend | number | Only include rows with at least this spend. |
sort_by | enum (spend) | Column to sort by: spend, sales, direct_sales, orders, units_sold, roas, acos, ctr, cpc, cvr, impressions, clicks, viewability_rate, video_completions, order_name, line_item_name, or creative_name. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by video_completions or video_completion_rate to compare video creative engagement.
- Use min_spend to return DSP rows with enough spend volume for stable comparisons.
- Compare viewability_rate against ROAS to separate media quality issues from conversion issues.
Watch out
- DSP rows appear only for tenants whose Amazon Ads account has manager-account access to DSP advertisers.
get_store_performanceReadGet Amazon Brand Store performance from Stores Analytics API snapshots, including page views, visits, visitors, orders, units, sales, dwell time, bounce rate, and new-to-store counts.
When to use
Use this to understand how shoppers move through Brand Stores by date, store, page, traffic source, or source tag, and which Store pages or traffic sources drive sales.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (yesterday) | End date (YYYY-MM-DD). Defaults to yesterday. |
dimension | enum (date) | Breakdown to return: date, store, page, source, or tag. |
profile_id | string | Filter by ad account profile ID. |
brand_entity_id | string | Filter by Brand Store entity ID. |
store_name | string | Filter by store name (LIKE match, use % for wildcards). |
page_id | string | Filter by Brand Store page ID. |
page_name | string | Filter by Brand Store page name (LIKE match, use % for wildcards). |
source | string | Filter by traffic source such as ADS, ORGANIC, or OTHER. |
tag | string | Filter by source tag name. |
min_views | number | Only include rows with at least this many page views. |
min_sales | number | Only include rows with at least this sales amount. |
sort_by | enum (views) | Column to sort by: date, store_name, dimension_value, views, visits, visitors, orders, units, sales, dwell_time, bounce_rate, or new_to_store. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Use dimension=page to find Store pages that get traffic but do not convert.
- Use dimension=source to compare Sponsored Brands, organic, and other Store traffic.
- Use dimension=tag to evaluate external links created with Store source tags.
Watch out
- Brand Store insights require the store_insights sync and only appear for advertisers with Brand Stores available to the Ads profile.
- Visitors and new_to_store are store-level/date metrics; page, source, and tag breakdowns may return zero for those columns.
get_portfolio_performanceReadGet Sponsored Products performance aggregated by portfolio ID, joined from campaign metrics and the latest campaign portfolio snapshot.
When to use
Use this when you manage budgets or goals by portfolio and need one row per portfolio instead of one row per campaign.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (30 days ago) | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
portfolio_id | string | Filter by portfolio ID. Use unassigned for campaigns without a portfolio. |
include_unassigned | boolean (true) | Include campaigns that are not assigned to a portfolio. |
sort_by | enum (spend) | Column to sort by. Includes standard metrics plus portfolio_id, campaign_count, profile_count, and avg_campaign_daily_budget. |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by spend to find the portfolios using the most budget.
- Filter portfolio_id=unassigned to return campaigns without a portfolio assignment.
- Use this before changing budgets when a seller allocates spend by portfolio rather than individual campaign.
Watch out
- Portfolio assignment comes from the latest campaign snapshot at or before the query end date, so historical performance is grouped by that snapshot assignment.
diagnose_performanceReadCross-dimensional root cause analysis comparing two time periods. Identifies top movers across campaigns, ad groups, and keywords/placements.
When to use
When performance changed (ACOS spiked, sales dropped, spend increased) and you need to understand why by pinpointing which campaigns, ad groups, and keywords drove the change.
Parameters
| Name | Type | Description |
|---|---|---|
current_start* | string | Current period start date (YYYY-MM-DD). |
current_end* | string | Current period end date (YYYY-MM-DD). |
compare_start* | string | Comparison period start date (YYYY-MM-DD). |
compare_end* | string | Comparison period end date (YYYY-MM-DD). |
profile_id | string | Filter by profile ID. |
campaign_name | string | Filter by campaign name (LIKE match). |
focus_metric | enum (acos) | Metric to focus root cause analysis on: spend, sales, acos, impressions, clicks. |
* required
Tips
- Use equal-length periods for fair comparison (e.g. 30 days vs prior 30 days).
- Start with focus_metric=acos, then follow up with spend or sales for deeper analysis.
- The output ranks top movers by absolute change, making it easy to spot the biggest contributors.
Watch out
- Ads data has a 3-day attribution lag. Avoid including the last 3 days in your comparison window.
update_keyword_bidsWriteUpdate keyword bids for Sponsored Products campaigns. Returns old and new bid values for each keyword. Max 100 keywords per call. Bids capped at $100. Always pre-reads current bids for audit trail.
When to use
Adjust individual keyword bids based on performance data, such as lowering bids on high-ACOS keywords or raising bids on high-converting keywords with low impression share.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Array of keyword bid updates (1-100 per call). Each item has keyword_id (string) and bid (number, min $0.02). |
* required
Tips
- Always check current bids with get_keyword_performance before making changes.
- Use get_bid_recommendations to get Amazon suggested bids as a baseline.
- Changes exceeding 500% of the current bid will trigger a warning in the response.
- The tool pre-reads current bids automatically, so the response shows before and after values.
Watch out
- Minimum bid is $0.02 and maximum is $100. Bids outside this range will be rejected.
update_keyword_stateWriteUpdate keyword state (ENABLED/PAUSED/ARCHIVED) for Sponsored Products keywords. Max 100 per call. Pre-reads current state for audit trail. ARCHIVED is irreversible.
When to use
Submit explicit keyword state changes after the caller has selected keyword IDs and target states.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Keyword state updates (1-100 per call). Each item has keyword_id (string) and state (ENABLED, PAUSED, or ARCHIVED). |
* required
Tips
- Use get_keyword_performance or get_search_terms to identify the keyword IDs before submitting state changes.
- The response shows old_state and new_state for each keyword ID.
- PAUSED keywords retain settings and can be re-enabled later.
Watch out
- ARCHIVED is irreversible. Once archived, a keyword cannot be re-enabled or modified.
update_adgroup_bidWriteUpdate default bid for Sponsored Products ad groups. Max 100 per call. Bid range: $0.02-$100. Warns on changes exceeding 500%. Pre-reads current bids for audit trail.
When to use
Change the default bid for an entire ad group when you want to adjust bid levels across all keywords in that group at once.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Array of ad group bid updates (1-100 per call). Each item has ad_group_id (string) and bid (number, $0.02-$100). |
* required
Tips
- The ad group default bid applies to new keywords and keywords without individual bids.
- Keywords with individual bids are not affected by ad group bid changes.
- Use get_adgroup_performance to identify groups that need bid adjustments.
Watch out
- Minimum bid is $0.02 and maximum is $100. Changes exceeding 500% trigger a warning.
update_campaign_biddingWriteUpdate placement bid adjustments for a Sponsored Products campaign. Adjusts Top of Search (TOS) and Product Page bid multipliers. Percentage range: 0-900%. Pre-reads current values for audit trail.
When to use
Increase or decrease bid multipliers for specific placements after analyzing placement performance data.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
campaign_id* | string | Campaign ID to update. |
adjustments* | array | Placement bid adjustments (1-2 per call). Each item has placement (PLACEMENT_TOP or PLACEMENT_PRODUCT_PAGE) and percentage (integer, 0-900). |
* required
Tips
- Use get_placement_breakdown to inspect placement-level conversion metrics for this campaign.
- A percentage of 50 means bids are increased by 50% for that placement. 0 means no adjustment.
- Top of Search placements typically convert best but cost more.
update_campaign_audience_bid_adjustmentWriteSet or remove the single audience bid adjustment for Sponsored Products campaigns. Percentage range: 0-900%. Pre-reads current values for audit trail.
When to use
Submit explicit audience bid adjustment values after the caller has selected campaign IDs, audience IDs, source type, and percentage.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Audience bid adjustment updates (1-100 per call). Each item has campaign_id, action (SET or REMOVE), and for SET: audience_id, audience_segment_type, and percentage. |
* required
Tips
- Use get_audience_segments to inspect available audience IDs before setting an adjustment.
- BEHAVIOR_DYNAMIC is used for Amazon-built audiences; SPONSORED_ADS_AMC is used for AMC custom audiences.
- Amazon currently allows one audience bid adjustment on a campaign; setting a new one replaces the campaign-level audience adjustment payload.
Watch out
- REMOVE clears the campaign audience bid adjustment by sending an empty adjustment list.
update_campaign_budgetWriteUpdate daily budget for a Sponsored Products campaign. Budget range: $1-$10,000. Warns on changes exceeding 500%. Pre-reads current budget for audit trail.
When to use
Submit a daily budget value for a Sponsored Products campaign after the caller has decided the target budget.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
campaign_id* | string | Campaign ID to update. |
budget* | number | New daily budget in dollars ($1-$10,000). |
* required
Tips
- Use get_budget_recommendations to inspect Amazon suggested budget fields alongside missed impressions, clicks, and sales.
- Use get_campaign_performance to inspect ROAS, ACOS, spend, and sales before submitting a budget value.
- The response shows the old and new budget values plus the percentage change.
Watch out
- Budget changes exceeding 500% of the current budget trigger a warning.
update_campaign_stateWriteUpdate campaign state (ENABLED/PAUSED/ARCHIVED) for Sponsored Products campaigns. Max 100 per call. Pre-reads current state for audit trail.
When to use
Submit ENABLED, PAUSED, or ARCHIVED state updates for Sponsored Products campaigns.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Campaign state updates (1-100 per call). Each item has campaign_id (string) and state (ENABLED, PAUSED, or ARCHIVED). |
* required
Tips
- PAUSED campaigns retain all settings and can be re-enabled later.
- Use get_campaign_performance to inspect ACOS, ROAS, spend, and sales before submitting state updates.
- PAUSED campaigns can be re-enabled later; ARCHIVED campaigns cannot be re-enabled.
Watch out
- ARCHIVED is irreversible. Once archived, a campaign cannot be re-enabled or modified.
update_campaign_audience_bid_adjustmentWriteSet or remove the single audience bid adjustment for Sponsored Products campaigns. Percentage range is 0-900%. Pre-reads current audience bid adjustment values for audit trail.
When to use
Attach, update, or clear a Sponsored Products campaign audience bid adjustment using an audience ID returned by get_audience_segments.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
updates* | array | Audience bid adjustment updates (1-100 per call). Each item has campaign_id, action (SET or REMOVE), and for SET: audience_id, percentage, and optional audience_segment_type. |
* required
Tips
- Use get_audience_segments to discover available audience IDs before setting an adjustment.
- Use action=REMOVE to clear the campaign audience bid adjustment.
- The response includes the old and new audience bid adjustment values for each campaign.
Watch out
- This tool controls the Sponsored Products campaign audience bid adjustment surface. It does not create Sponsored Brands or Sponsored Display audience targets.
create_keywordsWriteCreate exact, phrase, or broad keywords for Sponsored Products campaigns. Max 100 per call. Bid range: $0.02-$100.
When to use
Submit keyword creations when the caller has selected campaign IDs, ad group IDs, match types, and bid values.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
keywords* | array | Keywords to create (1-100 per call). Each item has campaign_id, ad_group_id, keyword_text, match_type (EXACT, PHRASE, or BROAD), and bid ($0.02-$100). |
* required
Tips
- Use get_search_terms to inspect customer search terms and matched targeting before creating keyword records.
- Use get_bid_recommendations to inspect Amazon suggested bid fields for the selected keyword context.
- Use create_negative_keywords separately when the caller has selected negative keyword records to submit.
create_negative_keywordsWriteCreate negative keywords for Sponsored Products campaigns. Items with ad_group_id are ad-group-level negatives, items without are campaign-level. Max 100 per call.
When to use
Submit campaign-level or ad-group-level negative keyword records selected by the caller.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
negatives* | array | Negative keywords to create (1-100 per call). Each item has keyword_text, match_type (NEGATIVE_EXACT or NEGATIVE_PHRASE), campaign_id, and optional ad_group_id. |
* required
Tips
- Use get_search_terms sorted by spend to inspect high-spend zero-sale search terms.
- Campaign-level negatives (no ad_group_id) block the term across all ad groups in that campaign.
- Use NEGATIVE_EXACT when you want to block only the exact phrase, and NEGATIVE_PHRASE to block any query containing that phrase.
get_budget_pacingReadGet Sponsored Products campaign budget pacing from daily Amazon Ads budget usage snapshots, including usage percent, estimated used budget, remaining budget, and exhausted or at-risk labels.
When to use
Inspect campaigns that are exhausting daily budgets and compare pacing over recent days.
Parameters
| Name | Type | Description |
|---|---|---|
start_date | string (7 days ago) | Start date (YYYY-MM-DD). Defaults to 7 days ago. |
end_date | string (today) | End date (YYYY-MM-DD). Defaults to today. |
profile_id | string | Filter by ad account profile ID. |
campaign_id | string | Filter by Sponsored Products campaign ID. |
campaign_name | string | Filter by campaign name (LIKE match, use % for wildcards). |
min_usage_percent | number | Only return campaigns at or above this budget usage percentage. |
at_risk_percent | number (80) | Threshold used to label campaigns as at_risk. |
latest_only | boolean (true) | Return the latest snapshot per campaign in the selected date range. |
sort_by | enum (budget_usage_percent) | Column to sort by: snapshot_date, campaign_name, campaign_id, budget_usage_percent, budget_remaining_amount, or usage_updated_at. |
sort_order | enum (desc) | Sort direction: asc or desc. |
limit | number (20) | Max rows to return (1-1000). |
include_raw_rows | boolean (false) | Set true to include full raw result rows in structuredContent. Defaults to false; text content still includes a small row preview. |
Tips
- Sort by budget_usage_percent descending to find campaigns running out of budget first.
- Use latest_only=false when you want a day-by-day history for a campaign.
- Pair with get_budget_recommendations to compare Amazon suggested budget fields with pacing snapshots.
Watch out
- Budget usage snapshots are captured by the budget_usage sync. New tenants need that sync to run before historical pacing appears.
get_bid_recommendationsLive APIGet suggested bid amounts for keywords. Requires either ASINs for a new ad group context or both campaign_id and ad_group_id for an existing ad group. Returns Amazon recommended bid themes with low, suggested, and high bids for each keyword.
When to use
Get Amazon suggested bid ranges before creating new keywords or adjusting existing bids, using either a planned ASIN set or an existing ad group as the auction context.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
keywords* | array | Keywords to get bid recommendations for (1-100). Each item has keyword (string) and match_type (EXACT, PHRASE, or BROAD). |
asins | array | ASINs for a new ad group context (1-50). Provide this or both campaign_id and ad_group_id. |
campaign_id | string | Existing campaign ID to use for bid recommendations. Requires ad_group_id. |
ad_group_id | string | Existing ad group ID to use for bid recommendations. Requires campaign_id. |
bidding_strategy | enum | Optional bidding strategy for new ad group recommendations: AUTO_FOR_SALES, LEGACY_FOR_SALES, MANUAL, or RULE_BASED. Ignored when campaign_id and ad_group_id are provided. |
* required
Tips
- The suggested_bid, range_low, and range_high values are returned by Amazon for the chosen campaign or ASIN context.
- The theme column preserves Amazon recommendation theme labels when returned by the API.
- Use keyword_performance separately when comparing Amazon suggested bid fields to historical seller performance.
Watch out
- This is a live API call with rate limiting. Avoid calling in tight loops.
- Amazon requires either ASIN context for a new ad group or campaign_id + ad_group_id for an existing ad group.
get_budget_recommendationsLive APIGet Amazon Ads budget recommendation API fields for campaigns, including suggested budgets and estimated missed impressions, clicks, and sales.
When to use
Return Amazon suggested budget levels and seven-day missed-impression, missed-click, and missed-sales fields for selected campaigns.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
campaign_ids* | array | Campaign IDs to get budget recommendations for (1-100, string array). |
* required
Tips
- High missed_impressions and missed_clicks indicate Amazon estimated delivery constrained by budget.
- Compare suggested_budget against current budget to quantify the difference between current and Amazon-suggested budget values.
- Use get_campaign_performance separately to inspect ROAS, ACOS, spend, and sales for the same campaigns.
Watch out
- This is a live API call with rate limiting. Avoid calling in tight loops.
- Amazon may return per-campaign errors in the same response when some campaign IDs are invalid or unavailable.
get_ad_eligibilityLive APICheck product eligibility for selected ad types. Defaults to Sponsored Products, Brands, and Display, and can optionally include DSP. Returns status rows for each ASIN or SKU Amazon reports.
When to use
Before setting up new campaigns, verify which ad types each ASIN qualifies for and understand any warnings or restrictions.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
asins* | array | ASINs to check eligibility for (1-50, string array). |
ad_types | array | Optional ad types to check. Supported values: SP, SB, SD, DSP. Defaults to SP, SB, SD. |
* required
Tips
- Check eligibility before creating campaigns to avoid wasted setup time.
- Ineligibility or warning details often point to listing issues such as missing images, restricted categories, or not winning the Buy Box.
- Amazon may return multiple SKU rows for a single ASIN when that ASIN is listed under more than one seller SKU.
- Sponsored Brands and Display commonly require brand or program eligibility, so many sellers will only see SP eligibility at first.
Watch out
- This is a live API call with rate limiting. Avoid calling in tight loops.
get_audience_segmentsLive APIDiscover available Amazon Ads audience segments for a profile, with optional free-text search and segment-type filters. Returns segment IDs, names, types, categories, providers, status, and descriptions.
When to use
Find the audience segment IDs available to a profile before setting Sponsored Products audience bid adjustments or building audience-based workflows.
Parameters
| Name | Type | Description |
|---|---|---|
profile_id* | string | Ad account profile ID. |
query | string | Free-text search for audience segment names or descriptions. |
segment_types | array | Audience segment types to include: IN_MARKET, LIFESTYLE, REMARKETING, or SIMILAR. |
max_results | number (25) | Maximum number of audience segments to return (1-100). |
* required
Tips
- Use query to narrow broad segment catalogs before handing IDs to campaign planning workflows.
- Filter segment_types when you already know whether you need in-market, lifestyle, remarketing, or similar-audience targeting.
- Keep max_results small for exploratory calls; expand only after the search terms are useful.
Watch out
- This is a live API call with rate limiting. Avoid calling in tight loops.
- Returned segment availability depends on the profile and marketplace.