{
  "openapi": "3.0.1",
  "info": {
    "title": "Etsy Scraper API - Listings, Prices, Tags & Keywords",
    "description": "Scrape Etsy listings with the fields sellers actually need: USD price, favourites, views, bestseller flag, all 13 SEO tags, materials, images, shop and category. Plus Etsy's own ranked keyword suggestions. Search, shop analysis or direct URLs. Pay per listing, no run-start fee.",
    "version": "1.0",
    "x-build-id": "8GWxrFv3fyRFJRtjO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/vonsensey~etsy-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-vonsensey-etsy-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/vonsensey~etsy-scraper/runs": {
      "post": {
        "operationId": "runs-sync-vonsensey-etsy-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/vonsensey~etsy-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-vonsensey-etsy-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": {
          "mode": {
            "title": "What to collect",
            "enum": [
              "search",
              "listings",
              "shop",
              "keywords"
            ],
            "type": "string",
            "description": "Search Etsy by keyword, pull specific listings you already have URLs for, analyse a shop's listings, or research keywords only. Every mode returns the same listing shape, so you can change your mind without changing your pipeline.",
            "default": "search"
          },
          "searchTerms": {
            "title": "Search terms",
            "type": "array",
            "description": "What to search Etsy for, one term per line — for example 'personalized leather wallet'. Used when mode is 'Search Etsy by keyword'. Each term is searched separately and results are deduplicated across all of them.",
            "default": [
              "handmade ceramic mug"
            ],
            "items": {
              "type": "string"
            }
          },
          "shopNames": {
            "title": "Etsy shop names",
            "type": "array",
            "description": "Etsy shop names to analyse, one per line — the name as it appears in etsy.com/shop/NAME. Used when mode is \"A shop's listings\". Listings are matched on the shop's own Etsy id, so listings from other shops that merely mention the name are dropped free of charge.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "keywordSeeds": {
            "title": "Keyword seeds",
            "type": "array",
            "description": "Seed terms to expand into Etsy's own ranked search suggestions, one per line. Used when mode is 'Keyword research only'. Each seed is expanded with buyer-intent modifiers and an A–Z sweep.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "listingUrls": {
            "title": "Etsy listing URLs",
            "type": "array",
            "description": "Etsy listing URLs or bare listing ids, one per line. Used when mode is 'Specific listing URLs'. Accepts any Etsy URL shape, including region-prefixed ones such as etsy.com/de/listing/123456789.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "locale": {
            "title": "Etsy locale",
            "enum": [
              "en-US",
              "en-GB",
              "de",
              "fr",
              "es",
              "it",
              "nl",
              "pl",
              "pt",
              "ja"
            ],
            "type": "string",
            "description": "Which Etsy storefront language and currency to read. This changes the titles, descriptions and currency you get back, and it changes which keyword suggestions Etsy returns — German shoppers and US shoppers do not search the same way. A normalised USD price is always included regardless.",
            "default": "en-US"
          },
          "maxItems": {
            "title": "Maximum listings",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Stop after this many listings across the whole run. This is the number you are billed for: listings that fail to resolve, listings excluded by your filters, error rows, shop summaries and coverage rows are all free.",
            "default": 100
          },
          "expandWithKeywords": {
            "title": "Expand each term with Etsy's own suggestions",
            "type": "boolean",
            "description": "Turn each search term into dozens of related Etsy-ranked queries before searching. This is how you get past a single query's natural result ceiling of roughly 100 listings — leave it off for a quick sample, turn it on to sweep a whole niche. The keywords found are returned as rows too.",
            "default": false
          },
          "maxListingsPerTerm": {
            "title": "Maximum listings per search term",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many listings to take from a single search term before moving to the next. Values above about 100 have little effect, because one Etsy search term runs out of distinct results around there — use 'Expand each term' for more.",
            "default": 100
          },
          "maxKeywords": {
            "title": "Maximum keywords",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "Stop after this many keyword rows. Only applies when mode is 'Keyword research only' or 'Expand each term' is on; otherwise no keyword is ever collected or charged.",
            "default": 300
          },
          "keywordModifiers": {
            "title": "Expand with buyer-intent modifiers",
            "type": "boolean",
            "description": "Also ask Etsy for suggestions on 'personalized X', 'custom X', 'X for men', 'X gift' and sixteen other shapes Etsy shoppers actually type. Finds the commercial long tail that a bare seed misses.",
            "default": true
          },
          "keywordAlphabet": {
            "title": "Expand with an A–Z sweep",
            "type": "boolean",
            "description": "Also ask Etsy for suggestions on the seed followed by each letter and digit — the 'alphabet soup' technique. Slower, and the single richest source of long-tail keywords.",
            "default": true
          },
          "keywordRecursionDepth": {
            "title": "Keyword recursion rounds",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "Re-expand the strongest keywords found and collect their suggestions too. Each round multiplies both the depth and the time. 0 disables it.",
            "default": 0
          },
          "includeVariations": {
            "title": "Include variations and personalisation options",
            "type": "boolean",
            "description": "Fetch each listing's variation properties — sizes, colours, personalisation fields and their values. Costs one extra request per listing and is never charged separately.",
            "default": false
          },
          "includeDescription": {
            "title": "Include the full description",
            "type": "boolean",
            "description": "Keep each listing's full description text. Turn it off for a much smaller dataset when you only need prices, tags and demand signals.",
            "default": true
          },
          "shopSummary": {
            "title": "Add a summary row per shop",
            "type": "boolean",
            "description": "Emit one free extra row per shop seen, aggregating the listings this run found: price range and median, total favourites, bestseller count, and the shop's most-used SEO tags. Always free.",
            "default": true
          },
          "minPriceUsd": {
            "title": "Minimum price (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Skip listings cheaper than this, in US dollars. Skipped listings are never charged. Leave empty for no minimum."
          },
          "maxPriceUsd": {
            "title": "Maximum price (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Skip listings dearer than this, in US dollars. Skipped listings are never charged. Leave empty for no maximum."
          },
          "onlyBestsellers": {
            "title": "Bestsellers only",
            "type": "boolean",
            "description": "Keep only listings Etsy has flagged as a bestseller. Everything else is skipped free of charge.",
            "default": false
          },
          "excludeDigital": {
            "title": "Exclude digital downloads",
            "type": "boolean",
            "description": "Skip digital and printable listings, keeping physical products only. Skipped listings are never charged.",
            "default": false
          },
          "maxCostUsd": {
            "title": "Maximum spend for this run (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "A hard ceiling on what this run may charge. The run stops cleanly the moment the next row would cross it, and still writes its coverage rows. Leave empty for no ceiling."
          },
          "concurrency": {
            "title": "Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many listings to resolve at once. The default is a good balance; raise it only if you are collecting tens of thousands of listings and the run is time-bound.",
            "default": 8
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}