Adverso
Browse all topics

Tool reference

Every tool, its parameters, and an example of the call your AI makes.

These are the tools that are live. All of them read. The write tools, and more read tools, are listed with their status in Read and write.

ToolAccessWhat it answersAd types
list_accountsreadThe accounts and marketplaces you can read, and which days have data.All
get_account_overviewreadTotals for a period, per ad type and per day.All
get_campaignsreadPerformance per campaign.SP · SB · SD
get_ad_groupsreadPerformance per ad group.SP · SB · SD
get_keywordsreadPerformance per keyword and per target.SP · SB · SD
get_search_termsreadWhat shoppers actually searched for.SP · SB
get_placementsreadPerformance per placement.SP · SB
get_productsreadAdvertising performance per product.SP · SD
get_adsreadPerformance per Sponsored Brands ad.SB
get_purchased_productsreadWhat was bought after a click, when it was not the advertised product.SP · SB · SD
get_matched_targetsreadWhere Sponsored Display ads actually showed.SD
get_invalid_trafficreadImpressions and clicks Amazon discarded as invalid.SP · SB · SD
get_product_historyreadBest-seller rank, price and availability of each product, day by day.All
get_structurereadThe account as it is set up now.SP · SB · SD

A star marks a required parameter. Everything else has a default, so a tool can be called with no arguments at all. The parameters shared by most tools are explained in Parameters, and what comes back in Reading the answers.

All tools

list_accounts

Read

Returns every marketplace on your plan: account name, seller or vendor, country, store, currency, and the first and last day with performance data. Call it first: the other tools need a period inside those days.

No parameters.

Ask

Which Amazon accounts can you see?

The call your AI makes

{}

get_account_overview

Read

Impressions, clicks, cost, orders, sales, units, ACOS and ROAS for a period: in total, per ad type (Sponsored Products, Brands, Display) and per day.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.

Ask

How did my ads do last week?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17"
}

get_campaigns

ReadSP · SB · SD

One row per campaign for a period, with the campaign name and state. For budgets, bidding strategy and bid adjustments per placement, use `get_structure`.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Which 10 campaigns spent the most last week, and what was their ACOS?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "cost",
  "limit": 10
}

get_ad_groups

ReadSP · SB · SD

One row per ad group for a period, with the names of the ad group and its campaign.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Show the ad groups of campaign 123456789012345, best sales first.

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "campaign_id": "123456789012345",
  "sort_by": "sales"
}

get_keywords

ReadSP · SB · SD

One row per keyword, product target or automatic target for a period, with the keyword text or the targeting expression, the match type and the current bid.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Which keywords have an ACOS above 50%?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "acos",
  "limit": 50
}

get_search_terms

ReadSP · SB

One row per search term (or product page the ad showed on) and the keyword or target that caught it. Use it to find wasted spend and new keywords. When the term is a product, the row carries that product's title and image.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Which search terms cost money last week without a single sale?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "cost",
  "limit": 100
}

get_placements

ReadSP · SB

One row per campaign and placement: top of search, product pages, rest of search, off Amazon.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Is top of search worth its price in my biggest campaign?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "campaign_id": "123456789012345"
}

get_products

ReadSP · SD

One row per advertised product (ASIN), added up over all campaigns, with the product's title, image, brand, category, price and availability.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Which products sold the most through ads last week?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "sales",
  "limit": 20
}

get_ads

ReadSB

One row per Sponsored Brands ad, with the ad's name, state, creative (headline, images, products) and landing page next to the figures.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

Which of my Sponsored Brands ads has the best ACOS this week?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "acos"
}

get_purchased_products

ReadSP · SB · SD

One row per advertised product and purchased product, with orders, sales and units and the details of both products. Use it to see which products sell together. Sponsored Brands rows have no advertised product. The figures use the same attribution window as the other tools.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
sort_bysales | orders | unitsHighest first. Default: sales.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose advertised or purchased product (ASIN or title) contains this text.
campaign_idstringOnly rows of this campaign.

Ask

When people click my ads, which other products of mine do they end up buying?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "orders",
  "limit": 20
}

get_matched_targets

ReadSD

One row per Display target and the product page it matched, with that product's title and image next to the figures. Use it to see which product pages a category or audience target reaches.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
sort_bycost | sales | clicks | impressions | orders | acos | roasHighest first. Default: cost.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.
searchstringOnly rows whose campaign, ad group, keyword, search term, ASIN, placement or product title contains this text.
campaign_idstringOnly rows of this campaign.

Ask

On which product pages did my Display ads show last week, and which of them sold?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "sort_by": "sales"
}

get_invalid_traffic

ReadSP · SB · SD

One row per campaign with the gross figures, the invalid ones Amazon removed and did not charge for, and the invalid share in percent. Amazon reports this per campaign name, so there is no campaign id. Highest number of invalid clicks first.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 6 days before date_to, so the period is 7 days.
date_todateLast day, as YYYY-MM-DD. Default: yesterday.
ad_typeSP | SB | SDSponsored Products (default), Sponsored Brands or Sponsored Display.
searchstringOnly campaigns whose name contains this text.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.

Ask

Which campaigns had the most invalid clicks this week?

The call your AI makes

{
  "date_from": "2026-11-11",
  "date_to": "2026-11-17",
  "ad_type": "SP"
}

get_product_history

Read

One row per product with its rank in its category now, at the start of the period, the best and worst in between, and a `history` list with one entry per day. Amazon only reports today's values, so the history starts on the day the marketplace was connected (`history_starts` in the answer). Lowest rank first.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
date_fromdateFirst day, as YYYY-MM-DD. Default: 29 days before date_to, so the period is 30 days.
date_todateLast day, as YYYY-MM-DD. Default: today.
searchstringOnly products whose ASIN, title or category contains this text.
limitintegerRows to return. Default 50, at most 500.
offsetintegerRows to skip, for the next page.

Ask

Which of my products lost the most rank in their category this month?

The call your AI makes

{
  "date_from": "2026-11-01",
  "date_to": "2026-11-19"
}

get_structure

ReadSP · SB · SD

No performance figures: the items themselves, with the complete record Amazon holds for each. Campaigns (budget, state, bidding strategy, bid adjustments per placement, targeting type, dates), ad groups, keywords, targets, negatives, product ads, ads and portfolios. Paused and archived items are included.

ParameterTypeWhat it does
marketplace_idstringWhich marketplace, from list_accounts. Leave it out when your plan has only one.
type*campaign | ad_group | keyword | target | negatives | product_ad | ad | portfolioWhat to list. negatives lists negative keywords and negative targets, at ad group and campaign level.
ad_typeSP | SB | SDLeave out for all ad types.
stateENABLED | PAUSED | ARCHIVEDLeave out for all states.
searchstringOnly items whose name, keyword, ASIN, SKU or product title contains this text.
campaign_idstringOnly items of this campaign.
limitintegerRows to return. Default 100, at most 500.
offsetintegerRows to skip, for the next page.

Ask

Which campaigns have a bid adjustment for top of search?

The call your AI makes

{
  "type": "campaign",
  "ad_type": "SP",
  "state": "ENABLED"
}