{
  "openapi": "3.0.1",
  "info": {
    "title": "Etsy Search & Product Scraper — Listings, Prices, Best Sellers",
    "description": "Live Etsy search as rows: id, title, price, rating, reviews, badges, shop, rank. Keyword, market, or category URL. Apify residential proxy included by default; $6 per 1,000 listing rows; nothing charged on blocked pages.",
    "version": "0.2",
    "x-build-id": "nokzkR35dlIuB74iF"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/publicrecords~etsy-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-publicrecords-etsy-search-scraper",
        "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/publicrecords~etsy-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-publicrecords-etsy-search-scraper",
        "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/publicrecords~etsy-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-publicrecords-etsy-search-scraper",
        "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": {
          "queries": {
            "title": "Search keywords",
            "type": "array",
            "description": "Keywords to search, one per line (e.g. ceramic mug). Each keyword lands on Etsy's /market page, then pages through Etsy's own search API — every listing on the page (rendered and lazy-loaded), in Etsy's rank order.",
            "items": {
              "type": "string"
            }
          },
          "sort": {
            "title": "Sort",
            "enum": [
              "relevance",
              "newest",
              "price_asc",
              "price_desc",
              "top_reviews"
            ],
            "type": "string",
            "description": "Order of results, as on Etsy's own sort menu. Applies to search keywords (a market phrase with a sort set runs as a keyword search).",
            "default": "relevance"
          },
          "minPrice": {
            "title": "Min price",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest price to include, in whole units of the shop currency shown to your proxy's region (e.g. 10 = $10). Leave empty for no minimum."
          },
          "maxPrice": {
            "title": "Max price",
            "minimum": 0,
            "type": "integer",
            "description": "Highest price to include, whole units. Leave empty for no maximum."
          },
          "marketPhrases": {
            "title": "Market phrases",
            "type": "array",
            "description": "Phrases for Etsy's /market/ pages (any phrase resolves). Example: personalized dog collar",
            "items": {
              "type": "string"
            }
          },
          "categoryUrls": {
            "title": "Category URLs",
            "type": "array",
            "description": "Etsy category pages, e.g. https://www.etsy.com/c/jewelry/necklaces (no query string). Read in Etsy's default order.",
            "items": {
              "type": "string"
            }
          },
          "maxPages": {
            "title": "Max pages per input",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Pages per input, 1–20 (Etsy's own cap). On the Standby/MCP endpoint one call stops at 240 s and says so (truncated:true with pagesDone/pagesRequested); big jobs belong in a batch run.",
            "default": 5
          },
          "maxItems": {
            "title": "Max listings per run (0 = no cap)",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many listing rows across all inputs. Default 20: one keyword on defaults costs $0.005 + 20 x $0.006 = $0.125. Raise it (or set 0 for no cap) to get more pages.",
            "default": 20
          },
          "maxCacheAgeHours": {
            "title": "Max snapshot age (hours)",
            "minimum": 0,
            "type": "integer",
            "description": "Serve a keyword from our recent snapshot of the same search when it is at most this many hours old and holds every row you asked for; otherwise fetch live. Snapshot rows say data_source \"cache\", stale true and as_of (when they were read live), and are charged like live rows. 0 = always fetch live.",
            "default": 24
          },
          "fillLazyCards": {
            "title": "Return every listing on the page",
            "type": "boolean",
            "description": "Etsy renders 12 cards and lazy-loads the rest (48 more on page 1). On, the run fetches them the way Etsy's own page does, so you get the whole page in rank order. Off, you get the 12 rendered cards per page only (faster, fewer requests on your proxy).",
            "default": true
          },
          "is_best_seller": {
            "title": "Bestsellers only",
            "type": "boolean",
            "description": "Only return listings marked Bestseller.",
            "default": false
          },
          "is_star_seller": {
            "title": "Star Seller shops only",
            "type": "boolean",
            "description": "Only return listings from Star Seller shops.",
            "default": false
          },
          "free_shipping": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "Only return listings with free shipping.",
            "default": false
          },
          "is_discounted": {
            "title": "On sale only",
            "type": "boolean",
            "description": "Only return listings currently on sale.",
            "default": false
          },
          "instant_download": {
            "title": "Digital downloads only",
            "type": "boolean",
            "description": "Only return digital download listings.",
            "default": false
          },
          "is_handmade_only": {
            "title": "Handmade only",
            "type": "boolean",
            "description": "Only return listings Etsy flags as handmade.",
            "default": false
          },
          "is_personalizable": {
            "title": "Personalizable only",
            "type": "boolean",
            "description": "Only return listings that offer personalization.",
            "default": false
          },
          "max_processing_days": {
            "title": "Ready to ship within (days)",
            "minimum": 1,
            "type": "integer",
            "description": "Only return listings whose processing time is at most this many days (Etsy's ready-to-ship filter)."
          },
          "ship_to": {
            "title": "Ships to (country code)",
            "type": "string",
            "description": "Two-letter code, e.g. US, GB, DE."
          },
          "source": {
            "title": "Source",
            "type": "string",
            "description": "Optional free-text label for this run (for example the Make template that started it). Copied onto every listing row and onto RUN_SUMMARY so template runs can be filtered. Leave empty if you do not need it.",
            "default": ""
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Etsy blocks datacenter IPs. Default: Apify Proxy RESIDENTIAL, included in the event prices (no separate proxy or compute charge). Your own residential proxy works too. A blocked page is never charged.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "US"
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}