Zenserp Batch API

openapi: 3.2.0
info:
  title: Zenserp Batch API
  description: Zenserp SERP API. Real-time and historical search engine result pages for Google (web, images, video, news, shopping, maps, reverse image, YouTube, trends), Bing, Yandex and DuckDuckGo, plus asynchronous batch fetching with webhook delivery, Google Shopping product pages, Google Trends, and the reference list endpoints for languages, countries, geo locations and search engines. Endpoint inventory taken from the Zenserp documentation and confirmed against live unauthenticated probes; the v2 and v1 surfaces run side by side.
  version: '2.0'
  contact:
    name: Zenserp Support
    url: https://zenserp.com/
    email: support@zenserp.com
  termsOfService: https://zenserp.com/terms-of-service/
  x-logo:
    url: https://zenserp.com/wp-content/uploads/2019/07/zenserp-logo.png
  x-source: https://app.zenserp.com/documentation (endpoint list decompiled from the docs SPA bundle /js/app.js) + live unauthenticated probes 2026-08-13
servers:
- url: https://app.zenserp.com
  description: Zenserp API host. Search, status and the list endpoints are under /api/v2; batches, trends and shopping product pages are under /api/v1.
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Batch
  description: Batch processing for multiple simultaneous queries.
paths:
  /api/v1/batches:
    get:
      operationId: listBatches
      summary: Get All Batches
      description: This endpoint lists all submitted batches of your apikey.
      tags:
      - Batch
      responses:
        '200':
          description: Array of submitted batches.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchResponse'
        '403':
          description: Forbidden -- API key is wrong, you don't have enough requests or you don't have enough rights to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found -- There were no results found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: submitBatch
      summary: Submitting a new Batch
      description: Submit a batch of SERP jobs to be fetched asynchronously. Results are POSTed back to webhook_url when the batch completes; polling by id is possible but the webhook notification system is recommended by Zenserp.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              webhook_url: https://example.com/zenserp-callback
              name: nightly-rank-check
              jobs:
              - type: search
                q: pied piper
                location: New York,New York,United States
              - type: search
                q: silicon valley tv show
                gl: US
                hl: en
      responses:
        '200':
          description: Batch accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '422':
          description: Validation failed -- one or more request parameters were rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: Forbidden -- API key is wrong, you don't have enough requests or you don't have enough rights to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found -- There were no results found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/batches/{id}:
    get:
      operationId: getBatch
      summary: Get Batch By Id
      description: This endpoint allows you to check the status of a batch and retrieve it's results. Zenserp highly recommends the webhook notification system over manual polling.
      tags:
      - Batch
      parameters:
      - name: id
        in: path
        required: true
        description: The batch identifier returned when the batch was submitted.
        schema:
          type: string
      responses:
        '200':
          description: Batch information including all available responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '403':
          description: Forbidden -- API key is wrong, you don't have enough requests or you don't have enough rights to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found -- There were no results found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchRequest:
      type: object
      description: Batch submission body, documented at https://app.zenserp.com/documentation#batches
      required:
      - jobs
      properties:
        webhook_url:
          type: string
          format: uri
          description: optional, string -- The URL where the results will be posted back to.
        name:
          type: string
          description: optional, string -- A name for the batch.
        jobs:
          type: array
          description: required, array -- List of jobs to be done. Each job carries the parameters of the endpoint named by its type.
          minItems: 1
          items:
            type: object
            properties:
              type:
                type: string
                description: 'optional -- Which endpoint to use, default: search.'
                enum:
                - search
                - shopping
                - trends
                default: search
              custom_id:
                type: string
                description: Optional caller-supplied identifier. When submitted it is echoed back in the request object of the webhook response.
              q:
                type: string
              gl:
                type: string
              hl:
                type: string
              location:
                type: string
              num:
                type: integer
              start:
                type: integer
              tbm:
                type: string
              device:
                type: string
              search_engine:
                type: string
    ValidationErrorResponse:
      type: object
      description: Zenserp validation error envelope, documented verbatim in the Error Codes section of the Zenserp documentation.
      properties:
        errors:
          type: array
          description: One object per failing request, keyed by parameter name.
          items:
            type: object
            additionalProperties:
              type: string
      example:
        errors:
        - q: no query specified.
          search_engine: search engine not found.
    BatchResponse:
      type: object
      description: A submitted batch and, once complete, its job results.
      properties:
        id:
          type: string
          description: Batch identifier.
        name:
          type: string
        status:
          type: string
        webhook_url:
          type: string
          format: uri
        jobs:
          type: array
          description: Job results. Each entry is the response of the corresponding API with an added job_id field.
          items:
            type: object
            additionalProperties: true
    ErrorResponse:
      type: object
      description: 'Zenserp error envelope for request-level failures. Verbatim example from the live API: {"error": "No apikey provided."}'
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: No apikey provided.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: API key passed in the request header.
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as a query parameter.