SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-amazon-ads-sp-insights-report

linkfox-amazon-ads-sp-insights-report

Marketing & growth

View repository

Updated 10-15 23:43

About this skill

Amazon Ads SP insights report retrieval

One-stop retrieval of two types of Sponsored Products specialized reports: the script passes developerProxy to pass profileId(server-side token parsing), automatically completing advertiser account mapping, report creation, waiting (usually about 2–10 minutes), multi-shard CSV download, and saving to disk. The script uses the fixed field combinations allowed by Amazon Reporting API v1 beta and does not accept caller-assembled arbitrary fields. For the complete field basis of Audience and Search Term Impression Share/Rank, see references/sp-audience-reporting-v1.md and references/sp-search-impression-share-v1.md。

Depends on linkfox-amazon-ads-auth(automatically checked at script startup; if not installed, exit 42, stderr prints DEPENDENCY_MISSING）。

⚠️ Multi-account scenario: profileId must be resolved before calling

Users often only speak in natural language ("US site", "Japan site", "my store"); all entry points of this Skill must obtain the numeric profileId before they can call. Handle in the following order,do not skip：

  1. First call linkfox-amazon-ads-auth 's authorized_stores.py, to pull the list of accounts × marketplaces the user has authorized.
  2. Match countryCode：
    • only 1 candidate → silently use the corresponding profileId; do not announce this number to the user.
    • ≥ 2 candidates → must use accountName to confirm with the user; choosing the first by default is prohibited.
    • 0 candidates → inform the user that this marketplace is not authorized, and guide them to use linkfox-amazon-ads-auth to complete authorization.
  3. Strictly prohibitedto ask the user to directly provide the profileId number.
  4. Strictly prohibitedto choose a default account on your own when the account is ambiguous.

For the complete decision table, see linkfox-amazon-ads-auth the multi-account scenario description in SKILL.md.

How to call

  • API endpoint：POST /amazonAds/developerProxy(the script internally calls three Ads v1 paths in order; for complete parameters/responses/error codes, see references/api.md）
  • Python script：python scripts/<脚本名>.py '<JSON 参数>' [--inline] [--no-cache](available scripts see below)
  • Cost constraint: this tool does not consume compute; for the same session, same report type, and same parameter combination, it calls only once by default, and successful results are cached for 24 hours. Failed, incomplete, or empty reports must not automatically change dates, switch accounts, or repeatedly probe.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-ads-sp-insights-report-<timestamp>.json（<cwd> is the working directory when the script runs;<session> is taken from the environment variable SESSION_ID; writing to /tmpis prohibited; if the current directory is not writable, report an error)
  • Report CSV shards are written to the same session's data/; the final response does not expose the Amazon presigned URL
  • Response body ≤ 8 KB: after saving to disk, print the complete JSON to stdout
  • Response body > 8 KB: after saving to disk, stdout outputs only a summary
  • Add --inline to force full printing to stdout (also saved to disk); add --no-cache to force re-fetch

Data reading suggestion: first look at the summary and preview; for the response JSON use jq / ConvertFrom-Json Extract on demand; read complete report rows from the file pointed to by dataFiles[].path using a CSV tool or Import-Csv , to avoid loading the entire report into context.

Resolve authentication and compute issues

When the following situations occur, follow references/onboarding.md to resolve them:

Abnormal situations

  • API Key not configured: the environment variable LINKFOX_AGENT_API_KEYis also not configured LINKFOXAGENT_API_KEY
  • Response with 401 or 402 status code
  • Response indicates insufficient compute, balance, plan, or quota

Core Concepts

  • Coverage: only covers two types of Reporting API v1 beta reports: Sponsored Products Audience and Search Term Impression Share/Rank
  • One-stop: automatically completes advertiser account mapping → create report → wait for generation → download all CSV/gzip shards → return preview and file paths
  • Dual entry points, shared flow: the two public entry points each fix the report type and share reporting_v1_workflow.py; do not execute the shared module directly
  • Fixed fields: the Agent does not select fields、groupBy or free filter conditions; the script constructs an Amazon officially compatible field combination according to the corresponding reference
  • Account identifier division of labor：profileId is used by the backend to select the current user's authorization;advertiserAccountId is queried and mapped by the script by default
  • v1 and v3 boundary: ordinary impression, click, spend, and conversion SP search term reports use linkfox-amazon-ads-report 's spSearchTerm, not this Skill
  • Beta constraint: Amazon currently marks Reporting API v1 as open beta; account availability scope, fields, and rate limits may change

Available scripts

Script Responsibility
get_sp_audience_report.py One-stop retrieval of SP Audience audience segment performance; supports ACCOUNT / CAMPAIGN / AD_GROUP granularity
get_sp_search_impression_share.py One-stop retrieval of SP search term impression share and impression share rank
check_auth_dependency.py Detect whether linkfox-amazon-ads-auth is installed

For complete parameters, internal call chain, and response structure, see references/api.md. When selecting Audience, read references/sp-audience-reporting-v1.md; when selecting Search Impression Share, read references/sp-search-impression-share-v1.md。

Agent invocation flow

When the Agent receives a "SP Audience" or "SP search term impression share" request,it mustfollow this order:

  1. Determine report type: Audience uses get_sp_audience_report.py; impression share/rank uses get_sp_search_impression_share.py. Call only one entry point at a time.
  2. Check reference: read the corresponding report reference to confirm field meanings, limits, and display focus.
  3. Resolve account: through the Ads Auth Skill, obtain the unique profileId and regionby site; when there are multiple candidates, confirm the account with the user first.
  4. Confirm date and granularity: creation mode must have startDate / endDate. If timeUnit is not specified, use DAILY; if Audience does not specify detailLevel , use ACCOUNT。
  5. Inform of wait time and invoke: explain that Amazon usually takes about 2–10 minutes, then run the selected entry point. The script will automatically map the account, create, poll, and download; do not manually split it into three business calls.
  6. Process results：success=true display report type, date, total row count, preview, and all file paths;totalRows=0 is a valid empty report.
  7. Processing not complete：status=STILL_PROCESSING is not a failure. First confirm with the user whether to continue, then use resumeHint.params and --no-cache to poll the same reportId, creating duplicate reports is prohibited.

Default conditions (used when the user does not specify)

Condition Default rule
Report type Choose one of the two based on user intent; do not fetch both report types at the same time
startDate / endDate Do not guess arbitrarily; ask first if the user has not provided a date
timeUnit DAILY
Audience detailLevel ACCOUNT
advertiserAccountId Do not pass, the script automatically maps based on profileId Auto-mapping
pollInterval 60 seconds
maxAttempts 10; forming a client wait window of about 10 minutes
Fields and filters Use the script's fixed officially compatible combination; custom ones are not accepted

Request examples

1. SP Audience report

python scripts/get_sp_audience_report.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY", "detailLevel": "ACCOUNT"
}'

2. SP Search Term Impression Share/Rank report

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY"
}'

3. Poll an existing reportId (recover the last incomplete report)

Continue using the original entry based on the original report type; only pass profileId、region、reportId and polling parameters:

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "reportId": "REPORT_ID",
  "pollInterval": 60, "maxAttempts": 20
}' --no-cache

Response format

Success:

{
  "success": true,
  "status": "COMPLETED",
  "reportId": "report-id",
  "reportKind": "audience",
  "totalRows": 42,
  "dataFiles": [{"part": 1, "path": "C:/.../part-01.csv", "rowCount": 42}],
  "preview": [{"audienceSegment.name": "In-market ..."}],
  "pollAttempts": 2,
  "elapsedSeconds": 60.2
}
  • Failure：success=false, and includes error, the masked details and _cacheable=false。
  • Incomplete：status=STILL_PROCESSING, and includes the original reportId、resumeHint.mode=poll-only、resumeHint.params and _cacheable=false。

Invocation principles

  • When the user explicitly specifies a report type, only call that type; do not arbitrarily replace it or generate another report at the same time
  • Search Impression Share must not append campaign, adGroup, target, keyword, groupBy, or custom fields
  • Access tokens, refresh tokens, LWA keys, or custom Amazon request headers must not appear in parameters; the script will recursively reject them before going online
  • When a report fails, truthfully display the Amazon error; do not blindly change parameters and rebuild
  • When the report is still being generated, reuse the same reportId; creating duplicate reports due to a long wait is prohibited
  • After success, display the CSV file path and necessary preview; do not display the full Token, internal authorization records, or Amazon presigned URLs
  • Present report data objectively; unless the user requests it, do not proactively expand it into business decision advice

Common errors

Status Meaning Suggestion
Missing or invalid parameter Missing profile, region, or creation date Fill in the parameters required by the corresponding reference before calling
Unsupported parameter(s) A field or dimension not supported by this report was passed Remove unsupported parameters; do not bypass the script's fixed field combination
HTTP 401 LinkFox Key or Amazon Ads authorization is invalid For LinkFox 401, go through onboarding; for upstream 401, use Ads Auth to refresh authorization
HTTP 403 Reporting API v1 is not enabled for the current Ads application or account Check the Ads API application and authorized account permissions; do not use v3 data to fabricate results
HTTP 429 Amazon Ads upstream rate limiting Keep polling at the per-minute level; do not retry intensively
status=FAILED Amazon report generation failed Pass through the failure details; do not automatically change parameters and rebuild
status=STILL_PROCESSING The client wait window has ended, but the report is still being generated Not a failure; after confirming with the user, use resumeHint.params to continue with the original reportId
totalRows=0 Report succeeded but there is no data for the current period Valid empty result; do not automatically expand the date range or switch accounts
exit 42 Required Skill not installed First install or load linkfox-amazon-ads-auth

Date and data

  • When creating a report, startDate / endDate must use YYYY-MM-DD, and startDate <= endDate
  • endDate must not be later than today; using the current day may yield incomplete data, so prefer yesterday or an earlier date
  • DAILY returns date.value；SUMMARY returns dateRange.value
  • Audience focuses on displaying audience name/type/source, country, impressions, clicks, spend, purchases, sales, and ROAS, and retains the currency field
  • Search Impression Share focuses on displaying searchTerm.value、metric.impressionShare and metric.impressionShareRank
  • A completed report may contain multiple shards; all must be retained and displayed dataFiles

Not Applicable

  • Regular SP search term performance report (impressions, clicks, spend, sales, conversions) → linkfox-amazon-ads-report of spSearchTerm
  • Regular SP / SB / SD v3 reports → linkfox-amazon-ads-report
  • Campaign, ad group, keyword, targeting, and budget entity management → linkfox-amazon-ads-manager
  • Authorization, account selection, and token refresh → linkfox-amazon-ads-auth
  • Sponsored Brands, Sponsored Display, Sponsored Television, Amazon DSP, Brand Analytics, Retail Analytics → not in this Skill

Amazon Ads API interface protection and retry guidance

When the same advertising account/profile receives consecutive 400, 403, 404, or 429 responses from the Amazon Ads API, the gateway returns 450, 453, 454, or 459 and briefly cools down. These custom status codes are not native Amazon statuses and do not indicate account suspension; the purpose is to avoid continuous anomalies or high-frequency calls increasing the risk to the advertising account.

Status and message Scope Trigger and cooldown Handling
450：400，请求异常，请优化您的参数 Advertising account/profile + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 20 minutes Stop retrying with the original parameters; check profileId, region, entity/report ID, date, and request body
453：403，店铺未授权，请先授权 All interfaces for the advertising account/profile More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calls for that advertising account; check Ads authorization, application permissions, profile ownership, and region
454：404，资源不存在，请优化您的参数 Advertising account/profile + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Confirm the resource ID, owning profile/region, resource status, and interface path
459：429限流中，请降低频率 Advertising account/profile + interface First time: 15 seconds; more than 2 times within 2 minutes: 30 seconds; more than 4 times within 3 minutes: 2 minutes Reduce concurrency, pagination, and polling frequency and back off progressively
  • Immediately stop automatic or concurrent retries; do not bypass protection by switching scripts or repeatedly creating tasks; prioritize following retryAfter、blockedUntil, and when there is none, follow the durations described in the table.
  • For 450/453/454, parameters, authorization, or resource identifiers must first be corrected; after cooldown, retry cautiously at most once; if triggered again, stop calling. During 453, stop all Ads API calls for that advertising account/profile.
  • Retain existing reportId and other task IDs; when the result of a write operation is uncertain, query the status first and do not directly replay.
  • First explain ad account protection to the user, then give the reason, handling, and waiting time. You may reply: "To protect the security of your Amazon Ads account, it has been detected that the Amazon Ads API continuously returned {reason}, and a brief protection period is currently in effect. Please first {handling action}, and try again after an estimated {waiting time}; this does not mean the account is banned, nor is it a plan or credit limit." Do not only say "LinkFox rate limiting" or "server busy".

Compute power consumption rules

No compute power is consumed.

Feedback:

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

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. 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.