Amazon Ads Report Retrieval

One-stop report retrieval: The script automatically completes report creation, waiting (about 2–10 minutes), downloading, and decompression, and directly returns readable structured data. The script itself does not make business decisions such as "which columns to select / how to group"; these are first retrieved by the agent from the corresponding

.md

file under

references/report-types/

and then explicitly passed to the script.

Depends on
linkfox-amazon-ads-auth
(Automatically checked when the script starts; exits with code 42 and outputs

DEPENDENCY_MISSING

to stderr if not installed).

⚠️ Multi-account scenario: Must resolve the profileId before calling

Users often use natural language (e.g., "US site", "Japan site", "my store"), and all scripts of this skill must obtain the numeric

profileId

to execute. Follow the steps below in order, do not skip any:

First call
```
authorized_stores.py
```
of
```
linkfox-amazon-ads-auth
```
to pull the list of user-authorized accounts × sites.
Match candidate profiles based on the site mentioned by the user (mapped to
```
countryCode
```
, e.g., US→
```
US
```
):
- Only 1 candidate → Silently take the corresponding profileId and proceed with the call; do not announce the profileId number to the user.
- ≥ 2 candidates (multiple authorized accounts under the same site) → Must clarify with the user, using
```
accountName
```
  to ask: "You have authorized accounts A and B for the US site, which one would you like to use this time?"
- 0 candidates → Inform the user that the site is not authorized, and guide them to complete authorization via
```
linkfox-amazon-ads-auth
```
  .
Strictly prohibit asking users to directly provide the profileId number.
Strictly prohibit bypassing clarification by "picking the first one" or "selecting default" when there is ambiguity.

The complete decision table can be found in Section 4 of Usage Scenarios in SKILL.md of

linkfox-amazon-ads-auth

Core Concepts

Coverage: All report types of SP / SB (based on the
```
.md
```
files under
```
references/report-types/
```
; SD / ST / DSP are not covered yet)
One-stop: The script internally and automatically completes report creation → waiting for generation (about 2–10 minutes) → downloading → decompression; the caller only needs to wait for the final result
Single script:
```
get_report.py
```
(covers all adProducts of SP / SB)
Metadata vs. Runtime Parameters:
- Available fields (timeUnit / groupBy / filters / all column names) for each report type are centralized in
```
references/report-types/<adProduct-dir>/<reportTypeId>.md
```
- Script runtime parameters (polling interval, access link validity, etc.) can be found in this document and
```
references/api.md
```

Available Scripts

Script	Responsibility
`get_report.py` ⭐	One-stop execution. Required parameters `adProduct` / `groupBy` / `columns` must be extracted by the agent from report-types/ and passed in
`check_auth_dependency.py`	Checks if linkfox-amazon-ads-auth is installed

Complete script parameters and response structure can be found in

references/api.md

Agent Calling Flow

When the Agent receives a request like "pull Amazon Ads reports", must follow the steps below in order:

Determine reportTypeId: Select based on user intent (e.g., "last week's spend"→
```
spCampaigns
```
; "which products sold well"→
```
spAdvertisedProduct
```
/
```
sbPurchasedProduct
```
; "what terms did users search to find me"→
```
spSearchTerm
```
)
Check reference: Open
```
references/report-types/<adProduct-dir>/<reportTypeId>.md
```
- frontmatter provides:
```
adProduct
```
  /
```
groupBy
```
  (recommended in Configuration table) /
```
timeUnit
```
  (enumerable) /
```
format
```
  /
```
dateRange
```
  /
```
filters
```
- Base metrics table provides: all column names allowed for this report type
Consult user for customizable conditions (skip if user replies "default/whatever" and proceed to default selection in Step 4):
- ```
timeUnit
```
  : DAILY (split by day) or SUMMARY (aggregated)
- ```
columns
```
  extension: Whether to add attribution columns (sales7d / purchases7d / acosClicks7d / roasClicks7d), video metrics, newToBrand, etc.
- ```
filters
```
  : Whether to filter campaignStatus / keywordType / adStatus, etc.
Construct columns based on user reply or default conditions (see "Default Conditions" section below)
Call the script: Explicitly pass in the three required fields
```
adProduct
```
/
```
groupBy
```
/
```
columns
```

Default Conditions (Used when user does not specify)

Condition	Default Rule
`timeUnit`	Date range ≤ 7 days → `DAILY` ; > 7 days → `SUMMARY`
`columns` Identity Dimension	Must include `date` for `DAILY` ; must include `startDate` + `endDate` for `SUMMARY` ; then add the primary key fields of the report (refer to the primary key corresponding to groupBy in frontmatter, such as campaignId+campaignName / advertisedAsin+advertisedSku / searchTerm / keyword, etc.)
`columns` Basic Metrics	`impressions` / `clicks` / `cost` (based on what exists in the report's Base metrics)
`columns` Attribution Metrics	Only add when user mentions intent like "sales/conversion/ROI/ACOS": `sales7d` / `purchases7d` / `acosClicks7d` / `roasClicks7d` (based on what exists in Base metrics)
`filters`	No filters applied (return full data)
`groupBy`	Take the first value in the frontmatter `groupBy` array (i.e., the primary dimension recommended by Amazon in the Configuration table)

Request Examples

All examples explicitly pass in the three required fields (

adProduct

groupBy

columns

1. SP Campaign Report (Most Common)

bash

python scripts/get_report.py '{
  "profileId": 1234567890, "region": "NA",
  "reportTypeId": "spCampaigns",
  "adProduct": "SPONSORED_PRODUCTS",
  "groupBy": ["campaign"],
  "columns": ["date","campaignId","campaignName","impressions","clicks","cost"],
  "startDate": "2026-04-27","endDate": "2026-05-03",
  "timeUnit": "DAILY"
}'

2. SP Search Term Report (with Attribution)

bash

python scripts/get_report.py '{
  "profileId": 1234567890, "region": "NA",
  "reportTypeId": "spSearchTerm",
  "adProduct": "SPONSORED_PRODUCTS",
  "groupBy": ["searchTerm"],
  "columns": ["searchTerm","keyword","matchType","impressions","clicks","cost",
              "sales7d","sales14d","purchases7d","acosClicks14d","roasClicks14d",
              "startDate","endDate"],
  "startDate": "2026-04-01","endDate": "2026-04-30",
  "timeUnit": "SUMMARY",
  "filters": [{"field":"keywordType","values":["BROAD","PHRASE","EXACT"]}]
}'

3. SB Ad Group Report

bash

python scripts/get_report.py '{
  "profileId": 1234567890, "region": "NA",
  "reportTypeId": "sbAdGroup",
  "adProduct": "SPONSORED_BRANDS",
  "groupBy": ["adGroup"],
  "columns": ["adGroupId","adGroupName","impressions","clicks","cost","purchases","sales","startDate","endDate"],
  "startDate": "2026-04-01","endDate": "2026-04-30"
}'

4. Poll an Existing reportId (Recover from previous timeout / manual recovery)

When the last run exited due to a too-short client polling window but the report is still being generated on Amazon's side, directly pass in

reportId

to skip creation and continue polling and downloading. In this mode, only

profileId

region

reportId

are required; other fields are optional.

bash

python scripts/get_report.py '{
  "profileId": 1234567890, "region": "NA",
  "reportId": "7df1ef5d-45ba-40cc-b607-ff2148cf4f5e",
  "maxAttempts": 60, "pollInterval": 30
}'

Auto-recovery: If the caller does not pass
reportId
and Amazon triggers deduplication for the same parameter request (returns HTTP 425
The Request is a duplicate of : <uuid>
), the script will automatically parse the old reportId and switch to polling that old report, no retry is needed.

Response Format

Success:

json

{
  "success": true,
  "reportId": "4ee811a0-...",
  "reportTypeId": "spCampaigns",
  "startDate": "2026-04-28", "endDate": "2026-05-04",
  "downloadPath": "C:/.../tmp/report_data.json",
  "extractedFileHttpUrl": "http://127.0.0.1:51234/download",
  "extractedFileHttpServeSeconds": 300
}

Failure:

json

{"error":"Upstream HTTP 400","httpStatus":400,
 "body":"{\"code\":\"400\",\"detail\":\"startDate to endDate range (32 days) must not exceed maximum range (31 days)\"}"}

Calling Principles

Only pull the specified reportTypeId if the user has specified it; do not replace it without permission
When report generation fails (non-2xx or status=FAILED), truthfully inform the user of the error reason; do not retry blindly
After success, fully display the local file path and access link of the report to the user, and remind them that the access link has a validity period (valid for 5 minutes by default, need to pull again if expired)
Timeout is not failure: When the script returns
```
status=STILL_PROCESSING
```
(exit code=2), it means the client has waited the default 10 minutes but the report is still being generated on Amazon's side. At this time, must explain the situation to the user and ask if they want to continue waiting; never treat it as a failure. Reference reply: "The report is still being generated on Amazon's side (waited 10 minutes), do you want to continue waiting? You can choose: A. Wait another ~20 minutes (maxAttempts=60), B. Wait another ~1 hour (maxAttempts=120), C. Stop now, I'll come back with the reportId later." If the user selects A/B → use
```
resumeHint.params
```
to switch to polling-only mode and continue running

Common Errors

Status	Meaning	Suggestion
`Missing required parameters: adProduct/groupBy/columns`	Caller did not explicitly pass in the three required parameters	Go back to Step 2 of "Agent Calling Flow", read and supplement the parameters from `references/report-types/<adProduct-dir>/<reportTypeId>.md`
`HTTP 401`	accessToken expired	Call `refresh_token.py` of ads-auth and retry
`HTTP 403`	No associated ad account or insufficient permissions	Check the manager account/ad account association in the Amazon Ads backend
`HTTP 400 "must not exceed maximum range"`	Date range exceeds limit (most are 31 days)	Split the pull and merge locally; refer to the frontmatter `dateRange.maxSpanDays` of the corresponding `.md` file for the specific limit
`HTTP 400` with `columns` / `groupBy` validation error	Column name misspelled / does not match reportTypeId / exceeds Base metrics	Check against the Base metrics table in the `.md` file
`status=FAILED` with `failureReason`	Upstream generation failed	Mostly due to date window or permission issues; handle according to the specific failureReason
`status=STILL_PROCESSING` (exit 2)	Client polling window exhausted but report is still being generated	Not a failure. stdout already contains `reportId` and `resumeHint.params` . Ask the user if they want to continue waiting, and use the params (with `reportId` + larger `maxAttempts` ) to switch to polling-only mode and continue running
`HTTP 425 "duplicate of"`	A report with the same parameters is already running	The script will automatically parse and switch to polling the old reportId; no intervention is needed from the caller under normal circumstances
exit 42	Dependent skill not installed	Install `linkfox-amazon-ads-auth` first

Dates and Data

Date range limit: Most reports allow 31 days;
```
sbPurchasedProduct
```
allows 731 days;
```
spGrossAndInvalids
```
/
```
sbGrossAndInvalids
```
/
```
sdGrossAndInvalids
```
allow 365 days (refer to frontmatter for details)
Lookback window: SP defaults to 95 days, SB defaults to 60 days, GrossAndInvalids defaults to 365 days; refer to frontmatter
```
dateRange.dataRetentionDays
```
for details
Data delay is about 12 hours; the script will output a warning to stderr but not block if
```
endDate >= today
```
Empty data does not equal error: If there is no campaign activity in the account during the period, the report will be generated successfully, and the JSON may be
```
[]
```
or all metrics are 0

Not Applicable

Brand Analytics / Retail Analytics / Attribution reports → Not covered by this skill
Report deletion / modification / scheduled tasks → Not covered by this skill
Entity metadata (campaign name, keyword match type, etc.) → Handled by
```
linkfox-amazon-ads-entity
```
Authorization / token → Handled by
```
linkfox-amazon-ads-auth
```

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

The functionality or purpose described in this skill does not match actual behavior
The skill's results do not match the user's intent
The user expresses dissatisfaction or praise about this skill
Anything you believe could be improved

Call the feedback API as specified in

references/api.md

. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.

linkfox-amazon-ads-report

NPX Install

Tags

SKILL.md Content (Chinese)

Amazon Ads Report Retrieval

⚠️ Multi-account scenario: Must resolve the profileId before calling

Core Concepts

Available Scripts

Agent Calling Flow

Default Conditions (Used when user does not specify)

Request Examples

1. SP Campaign Report (Most Common)

2. SP Search Term Report (with Attribution)

3. SB Ad Group Report

4. Poll an Existing reportId (Recover from previous timeout / manual recovery)

Response Format

Calling Principles

Common Errors

Dates and Data

Not Applicable