serpresult-com Meta API

openapi: 3.2.0
info:
  title: SerpResult Meta API
  version: 1.0.0
  summary: Search engine results as JSON.
  description: 'SerpResult returns the organic results of a web search as JSON. Two search

    endpoints, both synchronous: `GET /v1/query` runs one search and

    `POST /v1/bulk` runs up to 50 in one request. Everything else on this

    surface is the dashboard''s reporting and credential management. ## Authentication


    Public API calls send a secret key in the `Authorization` header:


    ```

    Authorization: Bearer sk_live_…

    ```


    Keys are minted in the dashboard (or through `POST /v1/api-keys` with a

    session cookie). `sk_live_` keys are for production traffic, `sk_test_` keys

    carry a lower rate limit. The dashboard''s session cookie is accepted on the

    same endpoints. Routes marked **session only** (usage, history, key

    management) refuse a bearer key: a key that could mint another key would

    make revoking the first one meaningless. Two more principals exist and are described as security schemes below:

    the marketing site''s keyless demo (`X-Demo-Origin`) and RapidAPI''s proxy

    (`X-RapidAPI-Proxy-Secret` + `X-RapidAPI-User`). Neither is something an

    integrator sends by hand. ## Targets and what each supports


    | target | page | num | safe |

    | --- | --- | --- | --- |

    | `google_search` | 1–5 | 1–20 | off, moderate, strict |

    | `bing_search` | 1 only | 1–20 | off, moderate, strict |

    | `duckduckgo_search` | 1 only | 1–10 | not supported |

    | `yahoo_search` | 1 only | 1–10 | off, moderate, strict |

    | `brave_search` | 1–5 | 1–20 | off, moderate, strict |

    | `yandex_search` | 1–5 | 1–10 | not supported |


    Anything outside a target''s row answers `400 unsupported_parameter`:

    `bing_search` refuses `page` above 1; `duckduckgo_search` refuses `page`

    above 1, `num` above 10 and any `safe` but `off`; `yahoo_search` refuses

    `page` above 1 and `num` above 10; `brave_search` refuses `page` above 5;

    `yandex_search` refuses `num` above 10 and any `safe` but `off`. A `geo` outside

    the supported list answers `400 unsupported_geo` with the list in `details`. ## Credits


    Every search costs one credit: one for `GET /v1/query`, one per row of

    `POST /v1/bulk`. A cache hit costs the same as a fresh search. An upstream

    failure (502 / 504) is still charged: the search was run and only the answer

    is missing. A request refused with 400 or 402, and a failure on our side

    (500), cost nothing. ## Plans and quotas


    Every account starts on the trial: 100 requests, granted once per email

    address, that never reset. The trial has no period at all — nothing rolls

    over, so there is no reset to wait for. A paid plan''s quota is measured over its subscription''s billing cycle, which

    renews monthly on the day the subscription started rather than on the 1st. `X-Quota-Reset` and `period.end` carry the exact moment it rolls over; read

    the reset off those rather than deriving it from a calendar. An account on a

    paid plan with no subscription cycle behind it — a RapidAPI subscriber, a

    plan set by hand — is measured over the calendar month in UTC instead,

    resetting at `00:00:00Z` on the 1st. | plan | $ / month | requests | extra requests | concurrency |

    | --- | --- | --- | --- | --- |

    | Trial | 0 | 100, once, for life | — | 1 concurrent request |

    | Starter | 9 | 5,000 / month | credit packs at $1.50 per 1,000 | 2 concurrent requests |

    | Growth | 49 | 75,000 / month | credit packs at $0.80 per 1,000 | 5 concurrent requests |

    | Business | 99 | 200,000 / month | credit packs at $0.60 per 1,000 | 10 concurrent requests |

    | Custom | contact us | quoted | quoted | 20 concurrent requests |


    A plan costs the same bought direct as it does through RapidAPI. Plans

    bought direct are sold through Polar, our Merchant of Record: Polar takes

    the payment, handles tax and issues the invoice, and the subscription,

    payment methods and invoice history are managed in its customer portal. ## Credit packs


    Every plan is hard-limited — nothing is ever served on credit.'
  contact:
    name: SerpResult support
    email: team@serpresult.com
  license:
    name: Proprietary
    url: https://serpresult.com/legal/terms
servers:
- url: https://api.serpresult.com
  description: Production.
- url: http://localhost:8787
  description: Local `wrangler dev`.
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: Meta
  description: Unauthenticated service endpoints.
paths:
  /health:
    get:
      tags:
      - Meta
      operationId: health
      summary: Liveness
      description: No authentication, no rate limit.
      security: []
      responses:
        '200':
          description: The Worker is up.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - environment
                properties:
                  status:
                    type: string
                    const: ok
                  environment:
                    type: string
                    enum:
                    - development
                    - production
              example:
                status: ok
                environment: development
  /openapi.json:
    get:
      tags:
      - Meta
      operationId: openapiDocument
      summary: This document
      description: No authentication, no rate limit. The YAML source rendered as JSON, cacheable for five minutes.
      security: []
      responses:
        '200':
          description: The OpenAPI 3.1 document.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              description: '`public, max-age=300`'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - openapi
                - info
                - paths
                properties:
                  openapi:
                    type: string
                    const: 3.1.0
                  info:
                    type: object
                  paths:
                    type: object
                additionalProperties: true
components:
  headers:
    X-Request-Id:
      description: The id of this request, identical to `request_id` in any error body. Quote it in a support request.
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A secret key from the dashboard: `Authorization: Bearer sk_live_…` or

        `Bearer sk_test_…`. Both are held to the account plan''s rate — 60 a

        minute on the trial, up to 1200 on a custom plan — and both spend the

        same quota. Accepted on `/v1/query`, `/v1/bulk`, `/v1/me` and the MCP

        endpoint `POST /mcp` only; a session-only route answers 401 to a key.

        '
    sessionCookie:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: 'The dashboard''s session cookie (`__Secure-better-auth.session_token` when

        served over HTTPS). Accepted everywhere a key is, and the only credential

        the session-only routes take. On the search routes it gets the plan''s

        per-minute limit or 120, whichever is higher.

        '
    demoOrigin:
      type: apiKey
      in: header
      name: X-Demo-Origin
      description: 'The marketing site''s keyless hero search. The header must equal the

        deployment''s configured demo origin, and the request must carry no

        `Authorization` header and no session cookie — a credential sent beside

        it is refused rather than re-metered. The principal is the client IP,

        limited to 5 requests a minute, with no account behind it. Accepted on

        `/v1/query` and `/v1/bulk`.

        '
    rapidApiProxy:
      type: apiKey
      in: header
      name: X-RapidAPI-Proxy-Secret
      description: 'Requests relayed by the RapidAPI marketplace. The proxy injects

        `X-RapidAPI-Proxy-Secret` (compared in constant time against the

        deployment''s secret) and `X-RapidAPI-User` (the marketplace account the

        call is attributed to). Integrators never send these themselves. When

        the marketplace secret is not configured, or the marketplace account

        mapping has not landed, every request on this path answers

        `401 unauthorized` — this branch currently answers 401.

        '