{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Bestsellers Rank Tracker — Movers & Shakers API",
    "description": "Track Amazon Best Sellers & New Releases rank changes: top 100 per category, 11 marketplaces, daily movers, new entrants & dropouts. $4 per 1,000 products.",
    "version": "0.1",
    "x-build-id": "peWO3FeNXcPnz61ec"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/jaybird~amazon-bestsellers-movers-shakers-tracker/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-jaybird-amazon-bestsellers-movers-shakers-tracker",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/jaybird~amazon-bestsellers-movers-shakers-tracker/runs": {
      "post": {
        "operationId": "runs-sync-jaybird-amazon-bestsellers-movers-shakers-tracker",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/jaybird~amazon-bestsellers-movers-shakers-tracker/run-sync": {
      "post": {
        "operationId": "run-sync-jaybird-amazon-bestsellers-movers-shakers-tracker",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "listUrls": {
            "title": "List URLs",
            "type": "array",
            "description": "Any Amazon list URL, e.g. https://www.amazon.com/gp/bestsellers/electronics, /gp/new-releases/books, /gp/movers-and-shakers/kitchen, /gp/most-wished-for/toys-and-games, /gp/most-gifted/beauty or an SEO-style /zgbs/ URL. The marketplace is taken from the domain.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "categoryNodeIds": {
            "title": "Category node IDs or department slugs",
            "type": "array",
            "description": "Alternative to URLs: Amazon browse node IDs (e.g. 172541 = Headphones on amazon.com) or top-level department slugs (e.g. electronics, books, ce-de on amazon.de). Combined with Marketplace and List types below.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Find the category for a product type, then fetch its list: the actor searches Amazon, reads the Best Sellers Rank of the top organic results, and picks the category most of them rank in (e.g. \"air fryer\" → Air Fryers). The chosen category is shown in each list's summary.",
            "items": {
              "type": "string"
            }
          },
          "asins": {
            "title": "ASINs to track",
            "type": "array",
            "description": "Track specific products' Best Sellers Rank in every category they rank in, with the change since the last run. Accepts ASINs (B0BJ1SWDNB) or product URLs (which keep their own marketplace).",
            "items": {
              "type": "string"
            }
          },
          "marketplace": {
            "title": "Marketplace",
            "enum": [
              "US",
              "UK",
              "DE",
              "FR",
              "IT",
              "ES",
              "CA",
              "JP",
              "IN",
              "MX",
              "AU"
            ],
            "type": "string",
            "description": "Amazon storefront used for category node IDs, keywords, bare ASINs and category-tree crawls. List and product URLs use their own domain.",
            "default": "US"
          },
          "listTypes": {
            "title": "List types",
            "type": "array",
            "description": "Which ranked lists to fetch for each category node ID, keyword or category-tree node. Note: Amazon has shown no Movers & Shakers, Most Wished For or Gift Ideas items since spring 2026; those lists return an EMPTY summary. Use rank tracking on Best Sellers to see the biggest movers yourself.",
            "items": {
              "type": "string",
              "enum": [
                "bestsellers",
                "new-releases",
                "movers-and-shakers",
                "most-wished-for",
                "gift-ideas"
              ],
              "enumTitles": [
                "Best Sellers",
                "New Releases",
                "Movers & Shakers",
                "Most Wished For",
                "Gift Ideas"
              ]
            },
            "default": [
              "bestsellers"
            ]
          },
          "topN": {
            "title": "Products per list (top N)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many ranks to return per list, up to 100 (Amazon's maximum). Every rank up to this number is verified; a list that comes back short is retried and then reported as FAILED rather than returned incomplete.",
            "default": 100
          },
          "crawlCategoryTree": {
            "title": "Crawl category tree",
            "type": "boolean",
            "description": "Also scrape the sub-categories below each list, down to the depth set below. With no URLs or node IDs, starts from all departments of the selected marketplace.",
            "default": false
          },
          "maxCategoryDepth": {
            "title": "Category depth",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Levels to crawl. 1 = only the given lists (or, from all departments, the top-level departments); 2 = plus their direct sub-categories; and so on.",
            "default": 1
          },
          "maxLists": {
            "title": "Maximum lists",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Safety cap on the number of lists one run scrapes when crawling the category tree. Each list is up to 100 products.",
            "default": 50
          },
          "trackingStoreName": {
            "title": "Rank history store",
            "type": "string",
            "description": "Named key-value store in your account where the actor keeps the latest snapshot of every list and tracked ASIN. Each run compares against it, so a scheduled run returns previousRank, rankChange, new entrants and dropouts automatically. Named stores never expire. Clear this field to turn tracking off.",
            "default": "amazon-bestsellers-rank-history"
          },
          "previousDatasetId": {
            "title": "Compare with dataset (optional)",
            "type": "string",
            "description": "Dataset ID of an earlier run of this actor to compare against instead of the rank history store, e.g. to diff against a specific day."
          },
          "canaryMode": {
            "title": "Health-check mode",
            "type": "boolean",
            "description": "For scheduled monitoring runs: mark the run as failed (so Apify emails you) if any list, ASIN or keyword fails or a request had to fall back to the residential proxy. Leave off for normal runs.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}