SerpKite Batches API

openapi: 3.2.0
info:
  title: SerpKite SERP Batches API
  version: 1.12.4
  description: 'Public search API (api.serpkite.com). Google results as clean JSON or Markdown

    for AI agents, plus a Google Custom Search–compatible endpoint. Official SDKs:

    `serpkite` on npm and PyPI, `github.com/serpkite/serpkite-go`. **Auth:** `Authorization: Bearer skt_live_…`. A bare `Authorization: skt_live_…`

    (no scheme) is also accepted, for MCP hosts that can''t add one. GET requests

    may pass `?api_key=` instead. `/customsearch/v1` also accepts Google''s `?key=`. **Bodies:** every vertical accepts `POST` with a JSON object or `GET` with the

    same parameters in the query string (only `GET /v1/search` is spelled out

    here). Unknown parameters are rejected with 400, and so is a parameter the

    endpoint would ignore (e.g. `time` on `/v1/scholar`, `ll` on `/v1/search`). To run many queries at once,

    use `POST /v1/batches`. **Formats:** `format=json` (default) returns the schemas below. `format=markdown` returns `text/markdown` for every vertical. `format=compact` and `fields=` return a reduced JSON object (same top-level

    keys, fewer item fields, `meta` always kept), so required item fields may be

    absent there. **Responses** share one envelope: `request` (the normalised request),

    `results` (the vertical''s primary list), vertical-specific extras and `meta`. All keys are snake_case. **Credits** are decimal numbers (e.g. `0.5`). Failed, empty and blocked

    responses are refunded. Every billed response carries `X-Credits-Used`,

    `X-Credits-Remaining`, `X-Cost-USD`, `X-Cache` (`HIT`|`MISS`), `X-Latency-Ms`,

    `X-Tokens-Estimate` and `X-Request-Id`. **Errors** share one body: `{"error":{"code","message","request_id"}}`. Upstream failures (`upstream_error`, `upstream_blocked`, `upstream_timeout`)

    are `503` with `Retry-After`, never billed and safe to retry. The API never

    returns `502` or `504`. `429` also carries `Retry-After`: `rate_limited` is

    the per-second limit; `daily_limit_reached` is the free daily limit of an

    account that never bought a pack, which resets at 00:00 UTC (the message

    names the limit and the billing page; buying any pack removes it). `403 account_restricted` means the account''s free use is paused because it

    appears to be one of several accounts run by the same person (same device

    or network, or requests in step with other accounts) or uses a disposable

    email address; buying any pack lifts it. **CORS:** `Access-Control-Allow-Origin: *` without credentials; the `X-*`

    headers above are exposed, so a browser playground can call the API with a key. The keyless `/playground/search` is the exception: it only answers serpkite.com

    and app.serpkite.com (other `Origin`s get 403). Credit table: search/news/images/videos/maps/places/shopping/scholar/patents/

    webpage/customsearch = 1 per page; place details = 1; `num=100` depth bundle = 7; reviews = 1 per 10;

    autocomplete = 0.5; `include_content` = +1 per fetched page;

    batches ×0.5 (from 2026-11-23 a batch depth request is 0.5 per page with

    results, without the bundle cap: `num=100` = 5); cache hit via `max_age` ×0.5. `engine=consensus` (search only) =

    the sum of one page per provider that returned results. **AI** (Claude writes, OpenAI''s Decisions API runs typed checks; a failed

    model step is never billed): an answer (`include_answer` on `/v1/search` and

    `/v1/news`, the model part of `/v1/answer`) = +2 over the result page, +4

    when it read pages (`include_content`, `/v1/answer` depth=standard);

    `/v1/extract` `summary` = +4 and `output_schema` = +4 per page;

    `/v1/research` = lite 30, standard 75, deep 200. Responses that used a

    model carry `meta.llm`. **AI assistants** (`/v1/chatgpt`, `/v1/gemini`, `/v1/copilot`,

    `/v1/ai_mode`, `/v1/brave_ai`): a `prompt` sent to the public assistant

    as a logged-out user; the response is its answer

    (`text`, `markdown`) with the `sources` it cited or listed,

    `search_queries`, `products` and `places` where the assistant shows them,

    and `mentions` for the brands and domains in `track`.'
servers:
- url: https://api.serpkite.com
- url: http://localhost:8080
security:
- bearer: []
tags:
- name: Batches
paths:
  /v1/batches:
    post:
      summary: Queue up to 100 requests for one endpoint at half price.
      operationId: createBatches
      description: 'Credits for the whole batch are reserved together: if the balance, spend cap, key limit or

        free daily cap can''t cover every valid request, none is queued and each gets the error

        (invalid requests get their own 400 entry either way). Each job is settled and refunded on

        its own once it runs. Half price applies to the search part; an AI surcharge

        (`include_answer`) is charged in full.


        **Retries.** Send an `Idempotency-Key` to make the call safe to retry: for 24 hours a

        repeat with the same key and the same body returns the first response (with

        `Idempotent-Replayed: true`) without queueing or billing again. The same key with a

        different body is rejected with 422 `idempotency_key_reused`; a repeat while the first

        call is still running gets 409.


        **Webhooks.** Every delivery is a `POST` with `X-SerpKite-Event: batch.completed`,

        `X-SerpKite-Delivery` (the job id), `X-SerpKite-Timestamp` (Unix seconds) and

        `X-SerpKite-Signature: v1=.")>`. Deliveries

        are always signed; the account''s secret is created with its first webhook and revealed by

        rotating it (dashboard Settings → Webhooks). Verify by recomputing the HMAC over the raw

        body, comparing in constant time, and rejecting timestamps older than 5 minutes. The SDKs

        ship `verifyWebhook` / `verify_webhook` / `VerifyWebhook`.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: 1-255 printable ASCII characters (e.g. a UUID). Retries with the same key and body replay the first response for 24 h
        schema:
          type: string
          minLength: 1
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateRequest'
      responses:
        '202':
          description: Queued. One entry per request, in order; an entry is a batch job or an error object
          headers:
            Idempotent-Replayed:
              description: '`true` when this is the stored response of an earlier call with the same Idempotency-Key'
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Unavailable'
      tags:
      - Batches
  /v1/batches/{id}:
    get:
      summary: Poll a batch job
      operationId: getBatch
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Batches
components:
  responses:
    Unavailable:
      description: 'Temporarily unavailable, not billed, safe to retry after `Retry-After`.

        Codes: `upstream_error` (the upstream page couldn''t be fetched or parsed),

        `upstream_blocked` (the upstream is rate limiting us or refused the query), `upstream_timeout`

        (the search took too long), `unavailable` (endpoint or dependency down).

        The API never sends 502 or 504.

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    BatchCreateRequest:
      type: object
      required:
      - endpoint
      - requests
      properties:
        endpoint:
          type: string
          enum:
          - search
          - images
          - videos
          - news
          - maps
          - places
          - place
          - reviews
          - shopping
          - scholar
          - patents
          - autocomplete
          - webpage
          - chatgpt
          - gemini
          - copilot
          - ai_mode
          - brave_ai
        requests:
          type: array
          minItems: 1
          maxItems: 100
          description: Request bodies for `endpoint` (same fields as the realtime endpoint)
          items:
            type: object
            additionalProperties: true
        webhook_url:
          type: string
          format: uri
          description: POSTed each job's result, always signed with X-SerpKite-Signature (v1=hex HMAC-SHA256 of `<timestamp>.<body>` with the account webhook secret; see createBatches). Defaults to the account webhook
    BatchCreateResponse:
      type: object
      required:
      - batches
      properties:
        batches:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Batch'
            - $ref: '#/components/schemas/Error'
    Batch:
      type: object
      required:
      - id
      - status
      - endpoint
      - created_at
      - poll_url
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
        endpoint:
          type: string
          examples:
          - /v1/search
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        credits_used:
          type: number
        poll_url:
          type: string
        webhook_url:
          type:
          - string
          - 'null'
        webhook_status:
          type:
          - string
          - 'null'
          enum:
          - pending
          - delivered
          - failed
          - null
        error:
          type:
          - object
          - 'null'
          properties:
            code:
              type: string
            message:
              type: string
        result:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Present when done; kept 24h. The endpoint's response body, or {markdown, meta} for format=markdown jobs
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: '403: spend_cap_reached, key_limit_reached, account_restricted, forbidden. 409/422: idempotency_key_reused. 422: target_unavailable (the URL you asked for failed: its site answered 404, its domain doesn''t resolve; resending won''t help), no_pages. 429: rate_limited, daily_limit_reached. 503: upstream_error, upstream_blocked, upstream_timeout, unavailable (the API never sends 502 or 504)'
              examples:
              - unauthorized
              - invalid_request
              - insufficient_credits
              - rate_limited
              - daily_limit_reached
              - spend_cap_reached
              - key_limit_reached
              - account_restricted
              - idempotency_key_reused
              - forbidden
              - not_found
              - upstream_error
              - upstream_blocked
              - upstream_timeout
              - unavailable
              - internal
            message:
              type: string
            request_id:
              type: string
  headers:
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      description: OAuth 2.1 for the remote MCP server only (authorization code + PKCE S256; app-api.serpkite.com is the authorization server).
      flows:
        authorizationCode:
          authorizationUrl: https://app-api.serpkite.com/oauth/authorize
          tokenUrl: https://app-api.serpkite.com/oauth/token
          refreshUrl: https://app-api.serpkite.com/oauth/token
          scopes:
            mcp: Use the SerpKite MCP tools, billed to your account
            offline_access: Stay connected with refresh tokens