openapi: 3.0.3 info: title: Thordata Scraper API version: 1.0.0 description: SERP API and Web Scraper API task launch endpoints on the Thordata scraper host. Derived from Thordata's own canonical SDK specification (thordata-sdk-spec v1.json) and the published documentation at https://doc.thordata.com/doc/overview. contact: name: Thordata Support email: support@thordata.com url: https://www.thordata.com/contact-us x-derived-from: https://raw.githubusercontent.com/Thordata/thordata-sdk-spec/main/v1.json x-derived-by: API Evangelist enrichment pipeline x-derived-on: '2026-08-11' servers: - url: https://scraperapi.thordata.com description: Scraper API (SERP, Builder, Video Builder) tags: - name: SERP API description: Real-time search engine results - name: Web Scraper API description: Pre-built site scrapers launched as asynchronous tasks paths: /request: post: operationId: searchSerp tags: - SERP API summary: Run a SERP API search description: Retrieve real-time search engine results as parsed JSON or raw HTML. Supports Google, Bing, Yandex and DuckDuckGo. Billed only on a 200 response. security: - ScraperBearer: [] - ScraperHeaderToken: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - engine properties: &id001 engine: type: string gl: type: string hl: type: string json: type: string enum: - '0' - '1' - '2' description: 1=json,0=html,2=both no_cache: type: string enum: - 'True' - 'False' num: type: string q: type: string description: 'Required unless engine is one of: yandex' render_js: type: string enum: - 'True' - 'False' start: type: string tbm: type: string tbs: type: string text: type: string description: 'Required when engine is one of: yandex' application/json: schema: type: object required: - engine properties: *id001 responses: &id002 '200': description: Success. Billed only when the payload code is 200. content: application/json: schema: $ref: '#/components/schemas/Envelope' '400': description: Bad Request - invalid parameters were passed. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' '401': description: Unauthorized - authentication failed; check token validity. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' '403': description: Forbidden - the target server refused to fulfill the request. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' '429': description: Too Many Requests - request rate exceeded the API limit. Retryable with exponential backoff. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' '500': description: Internal Server Error. Retryable with exponential backoff. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' '504': description: Timeout Error - the proxy server timed out waiting for the upstream server. Not billed. content: application/json: schema: $ref: '#/components/schemas/Envelope' /builder: post: operationId: runScraperTask tags: - Web Scraper API summary: Launch a Web Scraper API task description: 'Run a pre-built scraper from the Web Scraper Store against a list of inputs. Requires all three headers: Authorization bearer scraperToken, token, key.' security: - ScraperBearer: [] PublicToken: [] PublicKey: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: spider_name: type: string description: Target site key, e.g. amazon.com spider_id: type: string description: Scraper id, e.g. amazon_product_by-url spider_parameters: type: string description: JSON-encoded array of per-input parameter objects spider_errors: type: string description: Include per-input errors in the result set spider_universal: type: string description: Universal spider flag file_name: type: string description: Output file name; supports the {{TasksID}} template required: - spider_id - spider_name - spider_parameters responses: *id002 /video_builder: post: operationId: runVideoScraperTask tags: - Web Scraper API summary: Launch a video/audio Web Scraper API task description: Same contract as /builder plus common_settings for video/audio stream selection. security: - ScraperBearer: [] PublicToken: [] PublicKey: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: spider_name: type: string spider_id: type: string spider_parameters: type: string spider_errors: type: string file_name: type: string common_settings: type: string description: 'JSON string of video/audio settings: resolution (e.g. ''<=360p''), video_codec (vp9, h264), audio_format (opus, mp3, aac), bitrate (e.g. ''<=320''), selected_only (boolean)' required: - spider_id - spider_name - spider_parameters responses: *id002 components: securitySchemes: ScraperBearer: type: http scheme: bearer bearerFormat: Token description: Scraper token (THORDATA_SCRAPER_TOKEN) from Dashboard > Account Settings. ScraperHeaderToken: type: apiKey in: header name: token description: 'Alternate to bearer: scraperToken sent in the token header.' PublicToken: type: apiKey in: header name: token description: Public token (THORDATA_PUBLIC_TOKEN) from the Thordata Dashboard. PublicKey: type: apiKey in: header name: key description: Public key (THORDATA_PUBLIC_KEY) from the Thordata Dashboard. schemas: Envelope: type: object description: Thordata JSON envelope. The effective status is the payload `code` when present and not 200, otherwise the HTTP status (v1.json errors.precedence). properties: code: type: integer description: Application status code. 200 success, 300 not collected (not billed). msg: type: string description: 'Human-readable message. Alternate field names: message, error, detail, description.' data: description: Result payload; shape varies by operation.