This skill guides you on how to query and analyze Amazon product historical time-series data, helping Amazon sellers track price movements, BSR trends, rating changes, and other key product metrics over time.
Core Concepts
This tool provides historical time-series data for individual Amazon products (ASINs) powered by Keepa. It returns timestamped data points for various metrics, allowing trend analysis over a configurable time window (up to 365 days). Each query targets a single ASIN in a specific Amazon marketplace.
Time-series format: All data series are returned as arrays of {time, value} objects, where time is a timestamp and value is the metric at that point. BSR data includes a categoryName field along with a points array. Analyze these fields from the saved JSON directly. _dataQuery_executeDynamicQuery reads Linkfox session data stored in SLS, not arbitrary JSON files; its supported data mappings do not determine whether these time series can be analyzed.
BSR logic: A smaller BSR value means a better sales rank. Rank 1 is the top-selling product in its category. When a user says "BSR improved", it means the numeric value decreased; "BSR dropped" means the value increased.
Available Data Series
| Series | Parameter | Description |
|---|---|---|
| Buy Box Price | (always returned) | Buy Box price over time |
| Lowest New Price | showPrice=1 | Lowest marketplace new item price |
| List Price | showPriceList=1 | Strikethrough / list price |
| Deal Price | showPriceDeal=1 | Lightning deal price |
| Prime Exclusive Price | showPricePrime=1 | Prime-exclusive new item price |
| FBA Price | showPriceFba=1 | Third-party FBA new item price |
| FBM Price | showPriceFbm=1 | Third-party FBM new item price |
| Coupon Price | showPriceCoupon=1 | Post-coupon Buy Box price |
| Main Category BSR | showBsrMain=1 | Best Sellers Rank in the main (root) category |
| Seller Count | showSellerCount=1 | Number of active sellers |
| Rating | (always returned) | Product star rating over time |
| Rating Count | (always returned) | Number of ratings over time |
| Monthly Sales | (always returned) | Monthly unit sales volume |
| Sub-category BSR | (always returned) | Best Sellers Rank in sub-categories |
Supported Marketplaces
| Domain ID | Marketplace |
|---|---|
| 1 | Amazon.com (US) |
| 2 | Amazon.co.uk (UK) |
| 3 | Amazon.de (Germany) |
| 4 | Amazon.fr (France) |
| 5 | Amazon.co.jp (Japan) |
| 6 | Amazon.ca (Canada) |
| 8 | Amazon.it (Italy) |
| 9 | Amazon.es (Spain) |
| 10 | Amazon.in (India) |
| 11 | Amazon.com.mx (Mexico) |
| 12 | Amazon.com.br (Brazil) |
Default marketplace is 1 (US). Use domain=1 when the user does not specify a marketplace.
How to call
- API endpoint：
POST /keepa/productSeries(for full parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/keepa_product_history.py '<JSON 参数>' [--inline] - Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure/empty results, do not automatically try successive probes by changing keywords, paging, or changing the zip code; if further retrieval is needed, first explain to the user that it will incur additional consumption.
Output strategy (script default behavior)：
- Alwayswrite the full response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-series-<timestamp>.json（<cwd>is the working directory when the script runs, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error) - Response body ≤ 8 KB: after saving to disk, print the full JSON to stdout
- Response body > 8 KB: after saving to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, the length of the largest list field + the first 3 samples) - Add
--inlineto force full printing to stdout (also saved to disk)
Data reading suggestions: First look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.
Resolve authentication and compute issues
When the following abnormal situations occur, use references/onboarding.md to guide resolution:
Abnormal situations
- API Key not configured: The environment variable is not configured
LINKFOX_AGENT_API_KEY, andLINKFOXAGENT_API_KEY。 - Response 401 or 402 status code
- Response indicates insufficient compute or balance: The message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.
Parameter Guide
Required Parameters
- asin: The Amazon Standard Identification Number to query. Only a single ASIN per request is supported.
- domain: The Amazon marketplace domain ID (see table above). Always map the user's marketplace mention to the correct numeric ID.
Optional Parameters
- days: Number of historical days to retrieve (1-365, default 90). Use 30 for short-term, 90 for medium-term, 365 for long-term analysis.
- show* flags: Set any
show*parameter to1to include that data series. By default, only the core series (Buy Box price, rating, rating count, monthly sales, sub-category BSR) are returned.
How to Choose Parameters
- Price analysis: Enable
showPrice,showPriceList,showPriceDeal,showPriceCouponas needed for the specific price comparison the user wants. - FBA vs FBM comparison: Enable both
showPriceFbaandshowPriceFbm. - BSR deep-dive: Enable
showBsrMainto get the root category BSR alongside the always-returned sub-category BSR. - Competitive landscape: Enable
showSellerCountto see how many sellers are competing. - Full product overview: Enable all show flags for a comprehensive historical snapshot.
Usage Examples
1. Basic price history for a US product
asin: B0XXXXXXXX, domain: 1, days: 90
2. Long-term BSR trend (1 year) on the German marketplace
asin: B0XXXXXXXX, domain: 3, days: 365, showBsrMain: 1
3. Price comparison across fulfillment channels
asin: B0XXXXXXXX, domain: 1, days: 30, showPriceFba: 1, showPriceFbm: 1, showPrice: 1
4. Deal and coupon price tracking
asin: B0XXXXXXXX, domain: 1, days: 90, showPriceDeal: 1, showPriceCoupon: 1
5. Full product health check
asin: B0XXXXXXXX, domain: 1, days: 90, showPrice: 1, showPriceList: 1, showPriceDeal: 1, showPricePrime: 1, showPriceFba: 1, showPriceFbm: 1, showPriceCoupon: 1, showBsrMain: 1, showSellerCount: 1
Display Rules
- Present data clearly: Show time-series data in tables or describe trends; avoid subjective business advice unless the user explicitly asks for it.
- BSR clarification: When showing BSR data, remind users that lower values mean better (higher) sales ranks.
- Price formatting: Display prices with proper currency symbols matching the marketplace ($ for US, EUR for DE/FR/ES/IT, GBP for UK, JPY for JP, etc.).
- Time formatting: Present timestamps in a human-readable date format.
- Trend summarization: When data series are long, summarize the overall trend (e.g., "price decreased from $29.99 to $24.99 over 90 days") and highlight significant changes such as price drops, BSR spikes, or rating shifts.
- Error handling: When a query fails, explain the reason and suggest corrections (e.g., verify the ASIN is valid, check the marketplace domain ID).
- Single ASIN limitation: If the user asks about multiple ASINs, inform them that queries must be made one ASIN at a time, and run multiple sequential calls.
Important Limitations
- Single ASIN per query: Only one ASIN can be queried at a time. For multi-ASIN comparisons, make separate requests.
- Maximum 365 days: Historical data is limited to at most 365 days back.
- Data granularity: Data points are at irregular intervals depending on when Keepa captured changes, not at fixed daily intervals.
User Expression & Scenario Quick Reference
Applicable -- Historical product-level data queries on Amazon:
| User Says | Scenario |
|---|---|
| "What's the price history for this ASIN" | Price trend analysis |
| "Show me the BSR trend", "how is it ranking" | BSR tracking |
| "Has the price dropped recently", "any deals" | Price drop / deal detection |
| "How many sellers are on this listing" | Seller count trend |
| "What's the rating trend", "review count over time" | Rating / review tracking |
| "FBA vs FBM price", "who has the Buy Box" | Fulfillment price comparison |
| "Monthly sales for this product" | Sales volume trend |
| "Was there a price war on this ASIN" | Competitive pricing analysis |
| "Show me the Keepa chart", "Keepa data" | Explicit Keepa data requests |
Not applicable -- Needs beyond product-level historical data:
- Search term / keyword analysis (use ABA data instead)
- Advertising / PPC campaign data
- Listing copywriting or content optimization
- Category-wide or market-level aggregate trends (this tool is per-ASIN only)
- Real-time inventory or stock level checks
- Product reviews text or sentiment analysis
Boundary judgment: When users say "product research" or "competitor analysis", if it boils down to examining a specific ASIN's historical price, BSR, or sales data, this skill applies. If they need keyword data, market-wide trends, or advertising metrics, it does not apply.
Compute consumption rules
Billed according to dynamic rules: compute consumed = 0.045 × the Keepa tokens consumed by this historical trend query.
Important: The service of this skill is dynamically calculated by a multiplier and may consume a large amount of compute at once. The user must be reminded, and the user decides whether to continue.
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, set LinkFox Skills.