profileId

1. First call

   authorized_stores.py

   of

   linkfox-amazon-ads-auth

   to pull the list of user-authorized accounts × sites.
2. 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

     .
3. Strictly prohibit asking users to directly provide the profileId number.
4. Strictly prohibit bypassing clarification by "picking the first one" or "selecting default" when there is ambiguity.

linkfox-amazon-ads-auth

• 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

1. 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

   )
2. 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
3. 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.
4. Construct columns based on user reply or default conditions (see "Default Conditions" section below)
5. Call the script: Explicitly pass in the three required fields

   adProduct

   /

   groupBy

   /

   columns

reportId

profileId

region

reportId

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.

• 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

• 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

• 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

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

references/api.md