SerpKite Research API

openapi: 3.2.0
info:
  title: SerpKite SERP Research 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: Research
paths:
  /v1/research:
    post:
      summary: Start an async deep-research task — planned searches, page reading, a cited…
      operationId: createResearch
      description: 'Claude plans Google queries for `input`, the pages they find are read and

        ranked, a decision model checks whether the notes already cover the task (and

        drops off-topic sources), Claude reviews gaps and plans follow-up rounds, then

        writes a Markdown report citing numbered sources (and, with `output_schema`, a

        JSON value in `output`).


        | effort | credits | first-round queries | rounds | pages per query |

        |---|---:|---:|---:|---:|

        | lite | 30 | 3 | 1 | 2 |

        | standard | 75 | 5 | 2 | 3 |

        | deep | 200 | 8 | 3 | 4 |


        The flat price is reserved at enqueue and charged only when the report is

        written; failed research is refunded. A canceled task is charged 1 credit per

        search already run. Returns `202`; poll `GET /v1/research/{id}` or wait for the

        signed `research.completed` webhook. At most 20 crawl and research tasks per

        account may be queued or running at once (`429`).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRequest'
            example:
              input: compare espresso machines under $500 for a small office
              effort: standard
              output_schema:
                type: object
                properties:
                  winner:
                    type: string
      responses:
        '202':
          $ref: '#/components/responses/TaskAccepted'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Unavailable'
      tags:
      - Research
  /v1/research/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      summary: Poll a research task (kept for 24 hours)
      operationId: getResearch
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchTask'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Research
    delete:
      summary: Cancel a research task.
      description: '`404` when there is no such task, `409` when it already finished.'
      operationId: cancelResearch
      responses:
        '200':
          $ref: '#/components/responses/TaskCanceled'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
      tags:
      - Research
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'
    TaskAccepted:
      description: Queued. Poll `poll_url` or wait for the webhook
      headers:
        X-Credits-Reserved:
          description: The maximum price, reserved until the task ends
          schema:
            type: number
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
        Location:
          description: Path of the task (`/v1/{kind}/{id}`)
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TaskCreated'
          example:
            id: 01926a3e-7b2c-7c4e-9f1a-2b3c4d5e6f70
            kind: crawl
            status: queued
            created_at: '2026-10-03T12:00:00Z'
            poll_url: https://api.serpkite.com/v1/crawl/01926a3e-7b2c-7c4e-9f1a-2b3c4d5e6f70
            credits_reserved: 50
            webhook_url: null
    TaskCanceled:
      description: '`canceled` (it was queued: refunded at once) or `canceling` (it is running and stops at its next checkpoint)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TaskCancelResponse'
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ResearchTask:
      type: object
      required:
      - id
      - kind
      - status
      - created_at
      - credits_reserved
      - credits_used
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          const: research
        status:
          $ref: '#/components/schemas/TaskStatus'
        created_at:
          type: string
          format: date-time
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        credits_reserved:
          type: number
        credits_used:
          type: number
        webhook_status:
          type:
          - string
          - 'null'
          enum:
          - pending
          - delivered
          - failed
          - null
        progress:
          type:
          - object
          - 'null'
          additionalProperties: true
          properties:
            round:
              type: integer
            rounds:
              type: integer
            queries:
              type: integer
            sources:
              type: integer
            step:
              type: string
              enum:
              - searching
              - reviewing
              - writing
        result:
          description: Set once the report is written (a failed or canceled task may carry only `queries`)
          anyOf:
          - $ref: '#/components/schemas/ResearchResult'
          - type: object
            additionalProperties: true
          - type: 'null'
        error:
          $ref: '#/components/schemas/TaskError'
    ResearchRequest:
      type: object
      required:
      - input
      properties:
        input:
          type: string
          minLength: 1
          maxLength: 8000
          description: The research task in plain words (`q` is accepted as an alias)
        effort:
          type: string
          enum:
          - lite
          - standard
          - deep
          default: standard
          description: lite = 30, standard = 75, deep = 200 credits
        output_schema:
          type: object
          additionalProperties: true
          description: A JSON Schema (at most 16 KB); the report is also returned as a JSON value in `result.output`
        country:
          type: string
        language:
          type: string
        include_domains:
          type: array
          items:
            type: string
          maxItems: 20
        exclude_domains:
          type: array
          items:
            type: string
          maxItems: 20
        webhook_url:
          type: string
          format: uri
          description: Receives the signed `research.completed` event. Defaults to the account webhook
    ResearchSource:
      type: object
      required:
      - index
      - title
      - link
      properties:
        index:
          type: integer
        title:
          type: string
        link:
          type: string
        domain:
          type: string
        published_at:
          type: string
        query:
          type: string
          description: The query that found it
    ResearchResult:
      type: object
      required:
      - input
      - effort
      - report
      - citations
      - sources
      - queries
      properties:
        input:
          type: string
        effort:
          type: string
          enum:
          - lite
          - standard
          - deep
        report:
          type: string
          description: Markdown report with `[n]` citation markers
        citations:
          type: array
          items:
            $ref: '#/components/schemas/Citation'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/ResearchSource'
        queries:
          type: array
          items:
            type: string
          description: Every search the research ran
        stats:
          type: object
          properties:
            searches:
              type: integer
            sources:
              type: integer
            rounds:
              type: integer
        llm:
          $ref: '#/components/schemas/LLMUsage'
        output:
          description: 'output_schema only: the JSON value (null when it could not be produced)'
        output_error:
          type: string
    Citation:
      type: object
      required:
      - index
      - title
      - link
      properties:
        index:
          type: integer
          description: The `[n]` marker used in the text (1-based source number)
        title:
          type: string
        link:
          type: string
        domain:
          type: string
    TaskError:
      type:
      - object
      - 'null'
      description: Set when the task failed or was canceled
      properties:
        code:
          type: string
          examples:
          - no_pages
          - canceled
          - timeout
          - internal
        message:
          type: string
    LLMUsage:
      type: object
      description: The model that wrote this response's AI part and the tokens it used
      properties:
        provider:
          type: string
          examples:
          - anthropic
          - openai
        model:
          type: string
          examples:
          - claude-haiku-5-5
          - gpt-6-luna
        input_tokens:
          type: integer
        output_tokens:
          type: integer
    TaskCancelResponse:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - canceled
          - canceling
    TaskCreated:
      type: object
      required:
      - id
      - kind
      - status
      - created_at
      - poll_url
      - credits_reserved
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - crawl
          - research
        status:
          $ref: '#/components/schemas/TaskStatus'
        created_at:
          type: string
          format: date-time
        poll_url:
          type: string
        credits_reserved:
          type: number
        webhook_url:
          type:
          - string
          - 'null'
    TaskStatus:
      type: string
      enum:
      - queued
      - running
      - completed
      - failed
      - canceled
    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
    CreditsRemaining:
      schema:
        type: number
  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