Amazon Ads Read
Fetch Amazon metric rows for a report type + date range, served instantly from Adspirer's nightly-collected warehouse (no polling — Amazon reporting is async)
POST https://api.adspirer.ai/api/v1/tools/get_amazon_report/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
profile_id | string optional | Amazon Ads profile ID (advertiser account). Omit to use the user's selected account. Find IDs with list_amazon_profiles. |
offset | integer optional | Row offset (default 0). Paging is capped at the top ~5,000 by spend AND each page is a billed call — prefer FILTERS over paging to reach specific rows. default: 0 |
limit | integer optional | Rows per page (default/max 1000). Summary totals always cover ALL matching rows regardless of this. default: 1000 |
campaign_id | string optional | Only rows in this campaign ID. |
campaign_name_contains | string optional | Only campaigns whose name contains this text (case-insensitive). |
search | string optional | Substring match on the entity (search term / keyword / ASIN), case-insensitive. |
match_type | string optional | Filter to a match type (EXACT / PHRASE / BROAD). |
min_spend | number optional | Only rows that spent at least this much. |
max_spend | number optional | Only rows that spent at most this much. |
min_sales | number optional | Only rows with at least this much sales. |
min_clicks | integer optional | Only rows with at least this many clicks. |
min_impressions | integer optional | Only rows with at least this many impressions. |
min_acos | number optional | Only rows with ACOS% at or above this (finds inefficient spend). Rows with no sales have no ACOS and are excluded — use zero_sales for those. |
max_acos | number optional | Only rows with ACOS% at or below this (finds efficient spend). |
min_roas | number optional | Only rows with ROAS at or above this. |
max_roas | number optional | Only rows with ROAS at or below this. |
zero_sales | boolean optional | Only rows that spent with ZERO sales (wasted spend). Combine with min_spend to set a threshold. |
sort_by | string optional | Sort key: spend (default) | sales | acos | roas | clicks | impressions. |
sort_dir | string optional | asc | desc (default desc; use asc with sort_by=acos for most-efficient-first). |
report_type_id | string optional | Which Amazon report to fetch from the warehouse: spCampaigns | sbCampaigns | sdCampaigns | spSearchTerm | sbSearchTerm | spTargeting | sbTargeting | sdTargeting | spAdvertisedProduct | sdAdvertisedProduct | spPurchasedProduct | sbPurchasedProduct | sbAdGroup | sdAdGroup default: "spCampaigns" |
ad_product | string optional | SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY default: "SPONSORED_PRODUCTS" |
start_date | string required | YYYY-MM-DD |
end_date | string required | YYYY-MM-DD |
{
"arguments": {
"start_date": "string",
"end_date": "string",
"profile_id": "string",
"offset": 0,
"limit": 1000,
"campaign_id": "string",
"campaign_name_contains": "string",
"search": "string"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for get_amazon_report)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "get_amazon_report"
}
{
"success": false,
"error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n - Acme Holdings (ad_account_id=\"act_123456789\")\n - Acme EU (ad_account_id=\"act_987654321\")",
"is_error": true,
"tool": "get_amazon_report"
}
{
"success": false,
"error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
"is_error": true,
"tool": "get_amazon_report",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
Interactive: Swagger UI
Machine-readable: OpenAPI 3.1 spec · llms-full.txt
More tools: Amazon Ads · All tools
Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai