{
  "openapi": "3.0.1",
  "info": {
    "title": "Marketplace Search Scanner: Amazon, eBay, Etsy",
    "description": "For any keyword, see the market on Amazon, eBay, Etsy, Walmart, Target, Best Buy, Home Depot and Lowe's: every listing with price, seller and reviews, plus price percentiles, seller concentration, review depth and new entrants since your last run. Only your Apify account needed.",
    "version": "0.3",
    "x-build-id": "Fd1LPEqwLRsYJhOVD"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/cleanpull~marketplace-search-scanner/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-cleanpull-marketplace-search-scanner",
        "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/cleanpull~marketplace-search-scanner/runs": {
      "post": {
        "operationId": "runs-sync-cleanpull-marketplace-search-scanner",
        "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/cleanpull~marketplace-search-scanner/run-sync": {
      "post": {
        "operationId": "run-sync-cleanpull-marketplace-search-scanner",
        "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": {
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Search terms, one per line, as shoppers type them.",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "title": "Marketplaces",
            "type": "array",
            "description": "Where to search. Amazon is read from its search page. Walmart and eBay are read from their search page through CleanPull's marketplace data service (seconds), or from its dataset when a page cannot be read (1 to 5 minutes). Etsy, Target and Best Buy come from the dataset (1 to 5 minutes; the keywords of a run are searched together). Home Depot and Lowe's are read from their search page only (one page: up to 24 results). Nothing to set up.",
            "items": {
              "type": "string",
              "enum": [
                "amazon",
                "ebay",
                "etsy",
                "walmart",
                "target",
                "bestbuy",
                "homedepot",
                "lowes"
              ],
              "enumTitles": [
                "Amazon",
                "eBay (ebay.com)",
                "Etsy",
                "Walmart",
                "Target",
                "Best Buy",
                "Home Depot",
                "Lowe's"
              ]
            },
            "default": [
              "amazon"
            ]
          },
          "amazonMarketplaces": {
            "title": "Amazon marketplaces",
            "type": "array",
            "description": "Country codes or domains, one per line: US, GB, DE, FR, IT, ES, CA, MX, BR, JP, IN, AU, NL, SE, PL, BE, TR, AE, SA, SG, EG, IE. Empty: US. Outside the US, pages are read from that country (residential add-on).",
            "items": {
              "type": "string"
            }
          },
          "maxResults": {
            "title": "Results per search",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Listings read per keyword and marketplace, in the order the marketplace shows them. Amazon: organic results (16 to 48 a page, up to 7 pages), plus the ads shown among them. Other marketplaces: up to this many results, each billed as a provider record.",
            "default": 48
          },
          "includeAds": {
            "title": "Amazon sponsored results",
            "type": "boolean",
            "description": "Also read Amazon's ads (sponsored listings). In the US, Amazon shows ads only to home-network visitors, so pages are read through residential addresses (add-on per page). Off: organic results only, cheaper.",
            "default": true
          },
          "brand": {
            "title": "Amazon: only this brand",
            "type": "string",
            "description": "Optional. On Amazon, keep only results whose title leads with this brand (any case or accents; \"for Sony\" or \"compatible with Sony\" products are not Sony's). Results of other brands are left out of every figure and listing row, and the summary's otherBrandsDropped counts them. Pages read and their cost are the same. A brand filter is its own watch. Empty: every result."
          },
          "ebayFixedPriceOnly": {
            "title": "eBay fixed price only",
            "type": "boolean",
            "description": "Leave auctions out of the listings. Either way, auctions are left out of the price figures, since a current bid is not a selling price. Auctions read are still provider records.",
            "default": false
          },
          "listingRows": {
            "title": "One row per listing",
            "type": "boolean",
            "description": "Return every listing read as its own row. Off: only the keyword summaries (and changes), cheaper.",
            "default": true
          },
          "watchlistName": {
            "title": "Watchlist name",
            "type": "string",
            "description": "Runs with the same name compare against each other: new entrants, new sellers, listings that left the top, and price-band moves.",
            "default": "default"
          },
          "changesOnly": {
            "title": "Changes only",
            "type": "boolean",
            "description": "Return only change rows (and the listings of new entrants). The first run of a watchlist returns its summaries as the baseline. Amazon pages and provider records read are still billed; unchanged searches deliver nothing else. Schedule it daily or weekly.",
            "default": false
          },
          "newEntrantTop": {
            "title": "Watch the top",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "New entrants and listings that left are counted in the top this many organic results, at most half the results read. A new entrant is a listing no earlier run saw anywhere in the results read (in the last 60 days) that is still in the top on the next run: one-off appearances and listings moving up from below do not count. A listing counts as gone only after 2 runs in a row without it.",
            "default": 24
          },
          "priceMoveMinPercent": {
            "title": "Smallest price-band move (%)",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "The median or a quartile price must move this much from the baseline, in the same direction on 2 runs in a row, to count as a price-band move. Result sets differ between reads, so small or one-off moves are noise.",
            "default": 10
          },
          "maxRunCostUsd": {
            "title": "Max cost per run (USD)",
            "minimum": 0.01,
            "maximum": 1000,
            "type": "number",
            "description": "Optional. A search starts only when what this run has charged, plus the most that search could cost, stays within this amount. For scheduled runs and tasks, where no spending limit may be set."
          },
          "maxItems": {
            "title": "Max rows",
            "minimum": 1,
            "type": "integer",
            "description": "Optional. Stop after this many rows."
          },
          "fields": {
            "title": "Only these fields",
            "type": "array",
            "description": "Optional. Keep only these fields, for example [\"keyword\", \"source\", \"title\", \"price\", \"seller\"].",
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Optional, Amazon only. The actor picks proxies itself (in-country addresses outside the US, residential for ads in the US). The other marketplaces come through CleanPull's marketplace data service."
          },
          "stateStoreName": {
            "title": "History store",
            "type": "string",
            "description": "Optional. A key-value store in your account where this actor keeps what it saw in earlier runs, so it can report changes. Empty: its own store, \"cleanpull-marketplace-scanner\". Pick one here when you run it with a scoped API token in Restricted access mode, so the run may use it. Without access to a history store, a run still completes and compares within itself."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}