{
  "openapi": "3.1.0",
  "info": {
    "title": "SerpResult",
    "version": "1.0.0",
    "summary": "Search engine results as JSON.",
    "description": "SerpResult returns the organic results of a web search as JSON. Two search\nendpoints, both synchronous: `GET /v1/query` runs one search and\n`POST /v1/bulk` runs up to 50 in one request. Everything else on this\nsurface is the dashboard's reporting and credential management.\n\n## Authentication\n\nPublic API calls send a secret key in the `Authorization` header:\n\n```\nAuthorization: Bearer sk_live_…\n```\n\nKeys are minted in the dashboard (or through `POST /v1/api-keys` with a\nsession cookie). `sk_live_` keys are for production traffic, `sk_test_` keys\ncarry a lower rate limit. The dashboard's session cookie is accepted on the\nsame endpoints. Routes marked **session only** (usage, history, key\nmanagement) refuse a bearer key: a key that could mint another key would\nmake revoking the first one meaningless.\n\nTwo more principals exist and are described as security schemes below:\nthe marketing site's keyless demo (`X-Demo-Origin`) and RapidAPI's proxy\n(`X-RapidAPI-Proxy-Secret` + `X-RapidAPI-User`). Neither is something an\nintegrator sends by hand.\n\n## Targets and what each supports\n\n| target | page | num | safe |\n| --- | --- | --- | --- |\n| `google_search` | 1–5 | 1–20 | off, moderate, strict |\n| `bing_search` | 1 only | 1–20 | off, moderate, strict |\n| `duckduckgo_search` | 1 only | 1–10 | not supported |\n| `yahoo_search` | 1 only | 1–10 | off, moderate, strict |\n| `brave_search` | 1–5 | 1–20 | off, moderate, strict |\n| `yandex_search` | 1–5 | 1–10 | not supported |\n\nAnything outside a target's row answers `400 unsupported_parameter`:\n`bing_search` refuses `page` above 1; `duckduckgo_search` refuses `page`\nabove 1, `num` above 10 and any `safe` but `off`; `yahoo_search` refuses\n`page` above 1 and `num` above 10; `brave_search` refuses `page` above 5;\n`yandex_search` refuses `num` above 10 and any `safe` but `off`. A `geo` outside\nthe supported list answers `400 unsupported_geo` with the list in `details`.\n\n## Credits\n\nEvery search costs one credit: one for `GET /v1/query`, one per row of\n`POST /v1/bulk`. A cache hit costs the same as a fresh search. An upstream\nfailure (502 / 504) is still charged: the search was run and only the answer\nis missing. A request refused with 400 or 402, and a failure on our side\n(500), cost nothing.\n\n## Plans and quotas\n\nEvery account starts on the trial: 100 requests, granted once per email\naddress, that never reset. The trial has no period at all — nothing rolls\nover, so there is no reset to wait for.\n\nA paid plan's quota is measured over its subscription's billing cycle, which\nrenews monthly on the day the subscription started rather than on the 1st.\n`X-Quota-Reset` and `period.end` carry the exact moment it rolls over; read\nthe reset off those rather than deriving it from a calendar. An account on a\npaid plan with no subscription cycle behind it — a RapidAPI subscriber, a\nplan set by hand — is measured over the calendar month in UTC instead,\nresetting at `00:00:00Z` on the 1st.\n\n| plan | $ / month | requests | extra requests | concurrency |\n| --- | --- | --- | --- | --- |\n| Trial | 0 | 100, once, for life | — | 1 concurrent request |\n| Starter | 9 | 5,000 / month | credit packs at $1.50 per 1,000 | 2 concurrent requests |\n| Growth | 49 | 75,000 / month | credit packs at $0.80 per 1,000 | 5 concurrent requests |\n| Business | 99 | 200,000 / month | credit packs at $0.60 per 1,000 | 10 concurrent requests |\n| Custom | contact us | quoted | quoted | 20 concurrent requests |\n\nA plan costs the same bought direct as it does through RapidAPI. Plans\nbought direct are sold through Polar, our Merchant of Record: Polar takes\nthe payment, handles tax and issues the invoice, and the subscription,\npayment methods and invoice history are managed in its customer portal.\n\n## Credit packs\n\nEvery plan is hard-limited — nothing is ever served on credit. An account\nthat needs more requests inside the period buys a **credit pack** up front:\n10,000, 50,000 or 100,000 credits, priced at its own plan's rate,\nthrough a Polar one-time checkout. The credits land on the account when\nPolar reports the order paid.\n\nPack credits **never expire** and are not tied to the subscription: they\nsurvive a cancellation and are still spendable on an account that has gone\nback to the trial. They are spent only after the period's quota is gone, so\nthe quota is always used first.\n\nBuying a pack needs an active subscription, because that is what prices it.\nSpending one never does.\n\n`/v1/query` and `/v1/bulk` answer with `X-Quota-Limit`, `X-Quota-Used`,\n`X-Quota-Remaining` and `X-Credits-Balance` on every response, plus\n`X-Quota-Reset` on a plan whose quota rolls over. The trial's never does, so\nthat header is absent on it. With both the quota and the balance spent, a\nrequest answers `402 quota_exceeded`, is not logged and is not charged; a\nbulk request carrying more rows than remain between the two is refused\nwhole, before any row runs.\n\nRapidAPI subscribers are metered and billed by the marketplace against the\ntier they subscribed to, so the quota headers and `402` do not apply on that\npath.\n\n## Rate limits\n\nA plan's concurrency is enforced as a request rate over a rolling 60-second\nwindow — one concurrent request is 60 requests a minute, so the trial gets\n60/min, Starter 120/min, Growth 300/min, Business 600/min and a custom plan\n1200/min. Counted per credential, one hit per HTTP request however many\nsearches a bulk request carries. An API key (live or test) and an MCP access\ntoken are held to the account plan's rate; the dashboard session gets that\nrate or 120/min, whichever is higher; the marketplace proxy 1200/min and the\nkeyless demo 5/min per client IP. `/v1/query`, `/v1/bulk` and `/v1/me`\nanswer with `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, and a\nrefused request is `429 rate_limited` with `Retry-After`.\n\n## Errors\n\nEvery error is a JSON envelope with the same three keys, plus `issues`\n(field-level validation messages) or `details` (the supported geo codes)\nwhere noted:\n\n```json\n{ \"error\": \"unsupported_geo\", \"message\": \"…\", \"request_id\": \"…\", \"details\": [\"us\", \"in\", \"…\"] }\n```\n\n`request_id` is also sent as the `X-Request-Id` header on every response,\nsuccess or failure. Send a UUID as `X-Request-Id` on the request to have it\nechoed; anything else is replaced. Any path not listed here answers\n`404 not_found` in the same envelope.\n",
    "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`."
    }
  ],
  "tags": [
    {
      "name": "Search",
      "description": "The metered search endpoints. Accept an API key, a session cookie, the demo header or the marketplace proxy."
    },
    {
      "name": "Account",
      "description": "The account behind the calling credential. Accepts an API key or a session cookie. Costs no credits."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "sessionCookie": []
    }
  ],
  "paths": {
    "/v1/query": {
      "get": {
        "tags": [
          "Search"
        ],
        "operationId": "query",
        "summary": "Run one search",
        "description": "Runs a single search against the requested target and answers its organic\nresults in rank order. Costs one credit on every 200, 502 and 504.\n\nPer-target rules, each violation answering `400 unsupported_parameter`:\n`google_search` and `brave_search` accept pages 1–5 and `num` 1–20;\n`bing_search` serves `page=1` only; `duckduckgo_search` serves `page=1`\nonly, caps `num` at 10 and takes no `safe` but `off`; `yahoo_search`\nserves `page=1` only and caps `num` at 10; `yandex_search` accepts\npages 1–5, caps `num` at 10 and takes no `safe` but `off`.\n",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          },
          {
            "demoOrigin": []
          },
          {
            "rapidApiProxy": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/query"
          },
          {
            "$ref": "#/components/parameters/target"
          },
          {
            "$ref": "#/components/parameters/geo"
          },
          {
            "$ref": "#/components/parameters/locale"
          },
          {
            "$ref": "#/components/parameters/page"
          },
          {
            "$ref": "#/components/parameters/num"
          },
          {
            "$ref": "#/components/parameters/safe"
          },
          {
            "$ref": "#/components/parameters/source"
          }
        ],
        "responses": {
          "200": {
            "description": "The search ran. `results.organic` may be empty when the engine returned nothing.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-Credits-Used": {
                "$ref": "#/components/headers/X-Credits-Used"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "examples": {
                  "google": {
                    "summary": "google_search, geo=us, num=3",
                    "value": {
                      "id": "qry_bbadb104fad74005a996dcd379a072cb",
                      "target": "google_search",
                      "query": "serp api",
                      "geo": "us",
                      "locale": "en-us",
                      "page": 1,
                      "results": {
                        "organic": [
                          {
                            "position": 1,
                            "title": "Search engine results page - Wikipedia",
                            "url": "https://en.wikipedia.org/wiki/Search_engine_results_page",
                            "domain": "wikipedia.org",
                            "snippet": "A search engine results page (SERP) is a webpage that is displayed by a search engine in response to a query by a user. Query: serp api."
                          },
                          {
                            "position": 2,
                            "title": "In-depth guide to how Google Search works",
                            "url": "https://developers.google.com/search/docs/fundamentals/how-search-works",
                            "domain": "google.com",
                            "snippet": "Google Search is a fully-automated search engine that uses software known as web crawlers that explore the web regularly to find pages to add to our index."
                          },
                          {
                            "position": 3,
                            "title": "SERP Features - What They Are & How to Rank For Them - Moz",
                            "url": "https://moz.com/learn/seo/serp-features",
                            "domain": "moz.com",
                            "snippet": "A SERP feature is any result on a Google Search Engine Results Page (SERP) that is not a traditional organic result."
                          }
                        ]
                      }
                    }
                  },
                  "bing": {
                    "summary": "bing_search, geo=gb, num=2",
                    "value": {
                      "id": "qry_f32fc4a882d0404f8228eb2599df2e6c",
                      "target": "bing_search",
                      "query": "bing webmaster guidelines",
                      "geo": "gb",
                      "locale": "en-gb",
                      "page": 1,
                      "results": {
                        "organic": [
                          {
                            "position": 1,
                            "title": "Bing Webmaster Guidelines",
                            "url": "https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a",
                            "domain": "bing.com",
                            "snippet": "These guidelines cover a broad range of topics and are intended to help you understand how Bing finds, indexes and ranks websites. Query: bing webmaster guidelines."
                          },
                          {
                            "position": 2,
                            "title": "Microsoft Bing - Wikipedia",
                            "url": "https://en.wikipedia.org/wiki/Microsoft_Bing",
                            "domain": "wikipedia.org",
                            "snippet": "Microsoft Bing, commonly referred to as Bing, is a search engine owned and operated by Microsoft."
                          }
                        ]
                      }
                    }
                  },
                  "brave": {
                    "summary": "brave_search, geo=de, num=2",
                    "value": {
                      "id": "qry_4a0c9de5b1f24a6c8d3e77a1c95b2f08",
                      "target": "brave_search",
                      "query": "brave search api",
                      "geo": "de",
                      "locale": "de-de",
                      "page": 1,
                      "results": {
                        "organic": [
                          {
                            "position": 1,
                            "title": "Brave Search API",
                            "url": "https://brave.com/search/api/",
                            "domain": "brave.com",
                            "snippet": "Power your search and AI apps with the fastest growing independent search engine since Bing."
                          },
                          {
                            "position": 2,
                            "title": "Brave Search - Wikipedia",
                            "url": "https://en.wikipedia.org/wiki/Brave_Search",
                            "domain": "wikipedia.org",
                            "snippet": "Brave Search is a search engine developed by Brave Software, built on an independent index of the web."
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request could not be run. `error` says why:\n\n- `invalid_request` — a parameter failed validation; `issues` lists each field.\n- `unsupported_geo` — `geo` is not a supported country; `details` lists the supported codes.\n- `unsupported_parameter` — the target cannot serve `page`, `num` or `safe` as sent (bing: `page` above 1; duckduckgo: `page` above 1, `num` above 10, any `safe` but `off`; yahoo: `page` above 1, `num` above 10).\n\nNo credit is charged.\n",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "unsupported_parameter": {
                    "summary": "bing_search with page=2",
                    "value": {
                      "error": "unsupported_parameter",
                      "message": "page is not supported for bing_search",
                      "request_id": "ff42f055-9ddf-4312-b524-74ce85151640"
                    }
                  },
                  "unsupported_num": {
                    "summary": "duckduckgo_search with num=20",
                    "value": {
                      "error": "unsupported_parameter",
                      "message": "num above 10 is not supported for duckduckgo_search",
                      "request_id": "9c6b1e40-2a77-4f3c-8b51-0d2e6a9f4417"
                    }
                  },
                  "unsupported_geo": {
                    "summary": "geo=zz",
                    "value": {
                      "error": "unsupported_geo",
                      "message": "geo must be a supported ISO 3166-1 alpha-2 country code; see details for the full list",
                      "request_id": "5ffaa523-2163-4e7f-8d46-bcc47d292de8",
                      "details": [
                        "us",
                        "in",
                        "gb",
                        "ca",
                        "au",
                        "de",
                        "fr",
                        "sg",
                        "ae",
                        "jp",
                        "ad",
                        "af",
                        "ag",
                        "al",
                        "am",
                        "ao",
                        "ar",
                        "at",
                        "aw",
                        "az",
                        "ba",
                        "bb",
                        "bd",
                        "be",
                        "bf",
                        "bg",
                        "bh",
                        "bi",
                        "bj",
                        "bn",
                        "bo",
                        "br",
                        "bs",
                        "bw",
                        "by",
                        "bz",
                        "cd",
                        "cg",
                        "ch",
                        "ci",
                        "cl",
                        "cm",
                        "cn",
                        "co",
                        "cr",
                        "cu",
                        "cv",
                        "cy",
                        "cz",
                        "dk",
                        "do",
                        "dz",
                        "ec",
                        "ee",
                        "eg",
                        "es",
                        "et",
                        "fi",
                        "fj",
                        "fm",
                        "fo",
                        "ga",
                        "gd",
                        "ge",
                        "gf",
                        "gg",
                        "gh",
                        "gm",
                        "gp",
                        "gq",
                        "gr",
                        "gt",
                        "gu",
                        "gy",
                        "hk",
                        "hn",
                        "hr",
                        "ht",
                        "hu",
                        "id",
                        "ie",
                        "il",
                        "iq",
                        "ir",
                        "is",
                        "it",
                        "jm",
                        "jo",
                        "ke",
                        "kg",
                        "kh",
                        "km",
                        "kn",
                        "kr",
                        "kw",
                        "ky",
                        "kz",
                        "la",
                        "lb",
                        "lc",
                        "lk",
                        "lr",
                        "ls",
                        "lt",
                        "lu",
                        "lv",
                        "ly",
                        "ma",
                        "md",
                        "me",
                        "mg",
                        "mk",
                        "ml",
                        "mm",
                        "mn",
                        "mo",
                        "mp",
                        "mq",
                        "mr",
                        "mt",
                        "mu",
                        "mv",
                        "mw",
                        "mx",
                        "my",
                        "mz",
                        "na",
                        "nc",
                        "ne",
                        "ng",
                        "ni",
                        "nl",
                        "no",
                        "np",
                        "nz",
                        "om",
                        "pa",
                        "pe",
                        "pf",
                        "pg",
                        "ph",
                        "pk",
                        "pl",
                        "pr",
                        "ps",
                        "pt",
                        "pw",
                        "py",
                        "qa",
                        "re",
                        "ro",
                        "rs",
                        "ru",
                        "rw",
                        "sa",
                        "sb",
                        "sd",
                        "se",
                        "si",
                        "sk",
                        "sl",
                        "sn",
                        "so",
                        "sr",
                        "st",
                        "sv",
                        "sy",
                        "sz",
                        "td",
                        "tg",
                        "th",
                        "tj",
                        "tl",
                        "tn",
                        "to",
                        "tr",
                        "tt",
                        "tw",
                        "tz",
                        "ua",
                        "ug",
                        "uy",
                        "uz",
                        "vc",
                        "ve",
                        "vg",
                        "vi",
                        "vn",
                        "vu",
                        "ye",
                        "za",
                        "zm",
                        "zw"
                      ]
                    }
                  },
                  "invalid_request": {
                    "summary": "num=99",
                    "value": {
                      "error": "invalid_request",
                      "message": "Too big: expected number to be <=20",
                      "request_id": "d8bf5452-3615-438b-899c-d77bf0948b34",
                      "issues": [
                        {
                          "field": "num",
                          "message": "Too big: expected number to be <=20"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "description": "The search provider could not be reached or answered with an unusable payload (`upstream_error`). One credit is charged.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-Credits-Used": {
                "$ref": "#/components/headers/X-Credits-Used"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": "upstream_error",
                  "message": "The upstream search provider could not be reached. Try again.",
                  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
                }
              }
            }
          },
          "504": {
            "description": "The search provider did not answer within the 15-second budget (`upstream_timeout`). One credit is charged.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-Credits-Used": {
                "$ref": "#/components/headers/X-Credits-Used"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": "upstream_timeout",
                  "message": "The upstream search provider did not answer in time. Try again.",
                  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
                }
              }
            }
          }
        }
      }
    },
    "/v1/bulk": {
      "post": {
        "tags": [
          "Search"
        ],
        "operationId": "bulk",
        "summary": "Run up to 50 searches",
        "description": "Runs every entry of `queries` and answers one result per entry, in input\norder, inside a single 60-second budget. A row is either a bare query\nstring or an object of per-row overrides; `target`, `geo` and `locale`\non the body are the defaults each row starts from.\n\nRows are independent: a row that fails validation or fails upstream is\nan error row, never a failed request. The HTTP status is 200 whenever\nthe body itself was accepted, even when every row failed. Rows still\nrunning when the budget expires are answered `upstream_timeout`.\n\nCredits: one per row that was actually dispatched to the search\nprovider, including rows that came back `upstream_error` or\n`upstream_timeout`. Rejected rows, rows that never started, and rows\nthat failed with `internal_error` cost nothing. The rate limiter counts\nthe whole request as one hit.\n\nQuota: on a hard-limited plan a batch carrying more rows than the quota\nhas left is refused whole with `402 quota_exceeded`, before any row runs.\n",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          },
          {
            "demoOrigin": []
          },
          {
            "rapidApiProxy": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkRequest"
              },
              "examples": {
                "mixed": {
                  "summary": "Batch defaults with one row overriding them",
                  "value": {
                    "target": "google_search",
                    "geo": "us",
                    "queries": [
                      "serp api",
                      {
                        "query": "bing webmaster guidelines",
                        "target": "bing_search",
                        "geo": "gb",
                        "num": 2
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The batch was accepted and every row has an outcome.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-Credits-Used": {
                "$ref": "#/components/headers/X-Credits-Used"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "One google row, one bing row, one rejected row",
                    "value": {
                      "batch_id": "bat_34218d7162344184bebcd4c1506b0e79",
                      "total": 3,
                      "succeeded": 2,
                      "failed": 1,
                      "results": [
                        {
                          "status": "ok",
                          "id": "qry_49eaefd2a3d24f4b960a6ea17c4ced18",
                          "target": "google_search",
                          "query": "serp api",
                          "geo": "us",
                          "locale": "en-us",
                          "page": 1,
                          "results": {
                            "organic": [
                              {
                                "position": 1,
                                "title": "Search engine results page - Wikipedia",
                                "url": "https://en.wikipedia.org/wiki/Search_engine_results_page",
                                "domain": "wikipedia.org",
                                "snippet": "A search engine results page (SERP) is a webpage that is displayed by a search engine in response to a query by a user. Query: serp api."
                              },
                              {
                                "position": 2,
                                "title": "In-depth guide to how Google Search works",
                                "url": "https://developers.google.com/search/docs/fundamentals/how-search-works",
                                "domain": "google.com",
                                "snippet": "Google Search is a fully-automated search engine that uses software known as web crawlers that explore the web regularly to find pages to add to our index."
                              },
                              {
                                "position": 3,
                                "title": "SERP Features - What They Are & How to Rank For Them - Moz",
                                "url": "https://moz.com/learn/seo/serp-features",
                                "domain": "moz.com",
                                "snippet": "A SERP feature is any result on a Google Search Engine Results Page (SERP) that is not a traditional organic result."
                              }
                            ]
                          }
                        },
                        {
                          "status": "ok",
                          "id": "qry_4595f489307f4bceb495c4263f3c5ce0",
                          "target": "bing_search",
                          "query": "bing webmaster guidelines",
                          "geo": "gb",
                          "locale": "en-gb",
                          "page": 1,
                          "results": {
                            "organic": [
                              {
                                "position": 1,
                                "title": "Bing Webmaster Guidelines",
                                "url": "https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a",
                                "domain": "bing.com",
                                "snippet": "These guidelines cover a broad range of topics and are intended to help you understand how Bing finds, indexes and ranks websites. Query: bing webmaster guidelines."
                              },
                              {
                                "position": 2,
                                "title": "Microsoft Bing - Wikipedia",
                                "url": "https://en.wikipedia.org/wiki/Microsoft_Bing",
                                "domain": "wikipedia.org",
                                "snippet": "Microsoft Bing, commonly referred to as Bing, is a search engine owned and operated by Microsoft."
                              }
                            ]
                          }
                        },
                        {
                          "status": "error",
                          "error": "unsupported_parameter",
                          "message": "page is not supported for bing_search"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The body itself failed validation (`invalid_request`, with `issues`). Nothing ran and nothing is charged.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              },
              "X-Quota-Limit": {
                "$ref": "#/components/headers/X-Quota-Limit"
              },
              "X-Quota-Used": {
                "$ref": "#/components/headers/X-Quota-Used"
              },
              "X-Quota-Remaining": {
                "$ref": "#/components/headers/X-Quota-Remaining"
              },
              "X-Credits-Balance": {
                "$ref": "#/components/headers/X-Credits-Balance"
              },
              "X-Quota-Reset": {
                "$ref": "#/components/headers/X-Quota-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": "invalid_request",
                  "message": "queries must contain between 1 and 50 entries.",
                  "request_id": "90d30843-bbe6-4e74-a287-8f514e722e24",
                  "issues": [
                    {
                      "field": "queries",
                      "message": "queries must contain between 1 and 50 entries."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getMe",
        "summary": "Retrieve your account",
        "description": "The account behind the calling credential: its email, plan, the credits\nit can still spend and, for an API key, the key's own name and mode. The\nrecommended connection test: a `200` means the credential is valid.\n\nCosts 0 credits and is not written to the query history. It counts as one\nhit against the caller's per-minute rate limit. A dashboard session gets\n`api_key: null`.\n",
        "responses": {
          "200": {
            "description": "The account.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                },
                "example": {
                  "email": "jane@acme.com",
                  "plan": "growth",
                  "credits_available": 48210,
                  "api_key": {
                    "id": "key_3f2a9c1e7b4d4e8a9f602c1d8e5b7a90",
                    "label": "Zapier",
                    "mode": "live"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A secret key from the dashboard: `Authorization: Bearer sk_live_…` or\n`Bearer sk_test_…`. Both are held to the account plan's rate — 60 a\nminute on the trial, up to 1200 on a custom plan — and both spend the\nsame quota. Accepted on `/v1/query`, `/v1/bulk`, `/v1/me` and the MCP\nendpoint `POST /mcp` only; a session-only route answers 401 to a key.\n"
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "The dashboard's session cookie (`__Secure-better-auth.session_token` when\nserved over HTTPS). Accepted everywhere a key is, and the only credential\nthe session-only routes take. On the search routes it gets the plan's\nper-minute limit or 120, whichever is higher.\n"
      },
      "demoOrigin": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Demo-Origin",
        "description": "The marketing site's keyless hero search. The header must equal the\ndeployment's configured demo origin, and the request must carry no\n`Authorization` header and no session cookie — a credential sent beside\nit is refused rather than re-metered. The principal is the client IP,\nlimited to 5 requests a minute, with no account behind it. Accepted on\n`/v1/query` and `/v1/bulk`.\n"
      },
      "rapidApiProxy": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Proxy-Secret",
        "description": "Requests relayed by the RapidAPI marketplace. The proxy injects\n`X-RapidAPI-Proxy-Secret` (compared in constant time against the\ndeployment's secret) and `X-RapidAPI-User` (the marketplace account the\ncall is attributed to). Integrators never send these themselves. When\nthe marketplace secret is not configured, or the marketplace account\nmapping has not landed, every request on this path answers\n`401 unauthorized` — this branch currently answers 401.\n"
      }
    },
    "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"
        }
      },
      "X-Credits-Used": {
        "description": "Credits charged by this response.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-RateLimit-Limit": {
        "description": "Requests allowed per rolling 60-second window for this credential.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests left in the window, after this one.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-RateLimit-Reset": {
        "description": "Unix time (seconds) at which the current window ends.",
        "schema": {
          "type": "integer"
        }
      },
      "X-Quota-Limit": {
        "description": "Requests the account's quota allows — this billing cycle on a paid plan, for life on the trial.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-Quota-Used": {
        "description": "Credits spent inside that quota as the request arrived. This response is not counted in it — read `X-Credits-Used` for what the response itself cost.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-Quota-Remaining": {
        "description": "Requests left in the period's quota as the request arrived. Never below 0 — once it reaches 0 the credit balance pays for the next request.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-Credits-Balance": {
        "description": "Pack credits left on the account AFTER this response, so whatever this request took out of the credit balance is already deducted. Spent only once `X-Quota-Remaining` is 0. Never expires, and survives the subscription that bought it.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "X-Quota-Reset": {
        "description": "Unix time (seconds) at which the quota resets: the end of the\nsubscription's billing cycle, or `00:00:00Z` on the 1st for an account\nwith no subscription cycle behind its plan. This header is the exact\nmoment — do not derive it from a calendar. **Absent on the trial**, whose\n100 requests never reset.\n",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Whole seconds to wait before retrying. Never below 1.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "parameters": {
      "query": {
        "name": "query",
        "in": "query",
        "required": true,
        "description": "The search terms. Surrounding whitespace is trimmed and runs of whitespace collapse to one space before the length check.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 400
        },
        "example": "serp api"
      },
      "target": {
        "name": "target",
        "in": "query",
        "description": "Which engine to search. Each one caps `page`, `num` and `safe` differently; see the `Target` schema.",
        "schema": {
          "$ref": "#/components/schemas/Target"
        }
      },
      "geo": {
        "name": "geo",
        "in": "query",
        "description": "The country the results are localized to. Also picks the default `locale`. An unsupported value answers `400 unsupported_geo`.",
        "schema": {
          "$ref": "#/components/schemas/Geo"
        }
      },
      "locale": {
        "name": "locale",
        "in": "query",
        "description": "Interface language and region as `xx-yy`, case-insensitive, stored\nlowercase. Every supported `geo` carries its own default — `us` is\n`en-us`, `jp` is `ja-jp`, `br` is `pt-br` — and omitting `locale` takes\nit. The docs list the default for each country under \"Targets and geo\".\n",
        "schema": {
          "$ref": "#/components/schemas/Locale"
        }
      },
      "page": {
        "name": "page",
        "in": "query",
        "description": "Result page. `google_search`, `brave_search` and `yandex_search` serve 1–5; `bing_search`, `duckduckgo_search` and `yahoo_search` serve 1 only and answer `400 unsupported_parameter` above it.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5,
          "default": 1
        }
      },
      "num": {
        "name": "num",
        "in": "query",
        "description": "How many organic results to answer, at most. Fewer come back when the page holds fewer. `google_search`, `bing_search` and `brave_search` accept 1–20; `duckduckgo_search`, `yahoo_search` and `yandex_search` cap at 10 and answer `400 unsupported_parameter` above it.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 10
        }
      },
      "safe": {
        "name": "safe",
        "in": "query",
        "description": "Safe-search level. Supported by every target but `duckduckgo_search` and `yandex_search`, which answer `400 unsupported_parameter` for anything but `off`.",
        "schema": {
          "$ref": "#/components/schemas/SafeSearch"
        }
      },
      "source": {
        "name": "source",
        "in": "query",
        "required": false,
        "description": "Optional attribution label stored with the search (for example `zapier`, `make`, `n8n`). Stored truncated to 32 characters. Defaults to `api` when omitted. Not returned in the response.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "example": "zapier"
      },
      "from": {
        "name": "from",
        "in": "query",
        "description": "Inclusive lower bound, an ISO 8601 date (`2026-09-07`, read as that day's start) or timestamp (`2026-09-07T13:00:00Z`), UTC.",
        "schema": {
          "type": "string"
        },
        "example": "2026-09-01"
      },
      "to": {
        "name": "to",
        "in": "query",
        "description": "Inclusive upper bound. A bare date (`2026-09-07`) covers the whole of that UTC day. Must not be before `from`.",
        "schema": {
          "type": "string"
        },
        "example": "2026-09-08"
      },
      "api_key_id": {
        "name": "api_key_id",
        "in": "query",
        "description": "Only rows made with this key. Revoked keys are accepted. A key that is not on this account answers `400 invalid_request`.",
        "schema": {
          "type": "string"
        },
        "example": "key_0f3ab2f0d0c845feb2cbb2dbbd1b2fa7"
      },
      "apiKeyId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The key id, as returned by list or create.",
        "schema": {
          "type": "string",
          "pattern": "^key_[0-9a-f]{32}$"
        },
        "example": "key_0f3ab2f0d0c845feb2cbb2dbbd1b2fa7"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "No accepted credential (`unauthorized`). A session-only route answers this to a bearer key; the demo header answers this when a credential rides along with it.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "unauthorized",
              "message": "API key is not valid.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "The period's quota AND the credit balance are both spent\n(`quota_exceeded`). Every plan is hard-limited, so this is the answer on\nany of them. Nothing ran, nothing was logged and nothing was charged. On\n`POST /v1/bulk` this is also the answer to a batch carrying more rows\nthan `remaining` + `balance`, refused whole before any row runs. On a\npaid plan the way out is a credit pack; on the trial it is a paid plan,\nsince a pack is priced off a subscription. `resets_at` is `null` on the\ntrial, whose requests never come back.\n",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          },
          "X-Quota-Limit": {
            "$ref": "#/components/headers/X-Quota-Limit"
          },
          "X-Quota-Used": {
            "$ref": "#/components/headers/X-Quota-Used"
          },
          "X-Quota-Remaining": {
            "$ref": "#/components/headers/X-Quota-Remaining"
          },
          "X-Credits-Balance": {
            "$ref": "#/components/headers/X-Credits-Balance"
          },
          "X-Quota-Reset": {
            "$ref": "#/components/headers/X-Quota-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/QuotaExceededEnvelope"
            },
            "examples": {
              "trial_exhausted": {
                "summary": "The trial's 100 requests are spent",
                "value": {
                  "error": "quota_exceeded",
                  "message": "Your 100 free trial requests are used up. Upgrade to a paid plan to keep searching.",
                  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90",
                  "plan": "trial",
                  "quota": 100,
                  "credits_used": 100,
                  "remaining": 0,
                  "balance": 0,
                  "resets_at": null
                }
              },
              "quota_and_balance_spent": {
                "summary": "A paid plan with nothing left to spend",
                "value": {
                  "error": "quota_exceeded",
                  "message": "Monthly quota of 75000 requests is spent and your credit balance is empty. The quota resets on 2026-10-16. Buy a credit pack in the dashboard to keep searching.",
                  "request_id": "9b8c0e12-4a7f-4f0b-b3d2-6c1e5a9d7f42",
                  "plan": "growth",
                  "quota": 75000,
                  "credits_used": 75000,
                  "remaining": 0,
                  "balance": 0,
                  "resets_at": "2026-10-16T05:05:09.979Z"
                }
              },
              "batch_too_large": {
                "summary": "A batch bigger than the quota and balance together",
                "value": {
                  "error": "quota_exceeded",
                  "message": "This request needs 20 but only 6 remain (0 of the monthly quota plus 6 pack credits). Buy a credit pack in the dashboard to keep searching.",
                  "request_id": "4f2a9c81-6b3d-4e57-9f12-8c0d5a7e3b64",
                  "plan": "growth",
                  "quota": 75000,
                  "credits_used": 75000,
                  "remaining": 0,
                  "balance": 6,
                  "resets_at": "2026-10-16T05:05:09.979Z"
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "The credential's per-minute limit is spent (`rate_limited`). Wait `Retry-After` seconds.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "rate_limited",
              "message": "Rate limit of 20 requests per minute exceeded. Retry in 37 seconds.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
            }
          }
        }
      },
      "InternalError": {
        "description": "Something failed on our side (`internal_error`). The detail is in our logs under `request_id`. Nothing is charged.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "internal_error",
              "message": "The request could not be completed.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
            }
          }
        }
      },
      "BillingUnavailable": {
        "description": "`billing_unavailable`. Purchases are closed on this deployment — direct\ncheckout is switched off, or the deployment is not wired to Polar. The\nsame plans are sold on the RapidAPI listing, and `GET /v1/billing`\nreports the state in `checkout`. Existing subscriptions, the customer\nportal and usage are unaffected.\n",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "billing_unavailable",
              "message": "Direct subscriptions open soon. Until then, subscribe through RapidAPI.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
            }
          }
        }
      },
      "ValidationBadRequest": {
        "description": "A parameter or body field failed validation (`invalid_request`). `issues` lists each field.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "invalid_request",
              "message": "name must be between 1 and 64 characters.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90",
              "issues": [
                {
                  "field": "name",
                  "message": "name must be between 1 and 64 characters."
                }
              ]
            }
          }
        }
      },
      "ReportingBadRequest": {
        "description": "`invalid_request`. Either a parameter failed validation (`issues` lists\neach field: an unparseable date, `from` after `to`, a window over 366\ndays) or `api_key_id` names a key that is not on this account (no\n`issues`).\n",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "range": {
                "value": {
                  "error": "invalid_request",
                  "message": "from must not be after to",
                  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90",
                  "issues": [
                    {
                      "field": "from",
                      "message": "from must not be after to"
                    }
                  ]
                }
              },
              "foreign_key": {
                "value": {
                  "error": "invalid_request",
                  "message": "No API key with that id exists on this account.",
                  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
                }
              }
            }
          }
        }
      },
      "ApiKeyNotFound": {
        "description": "No key with that id on this account, or it is already revoked (`not_found`).",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": "not_found",
              "message": "No API key with that id exists on this account.",
              "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
            }
          }
        }
      }
    },
    "schemas": {
      "Target": {
        "type": "string",
        "description": "The engine to search.\n- `google_search`: pages 1–5, `num` up to 20, safe search supported.\n- `bing_search`: page 1 only, `num` up to 20, safe search supported.\n- `duckduckgo_search`: page 1 only, `num` up to 10, no safe search.\n- `yahoo_search`: page 1 only, `num` up to 10, safe search supported.\n- `brave_search`: pages 1–5, `num` up to 20, safe search supported.\n- `yandex_search`: pages 1–5, `num` up to 10, no safe search.\n",
        "enum": [
          "google_search",
          "bing_search",
          "duckduckgo_search",
          "yahoo_search",
          "brave_search",
          "yandex_search"
        ],
        "default": "google_search"
      },
      "Geo": {
        "type": "string",
        "description": "A supported country, as an ISO 3166-1 alpha-2 code. Results are\nlocalized to this country, the same ones a user searching there would\nsee, and the code also picks the default `locale`.\n",
        "enum": [
          "us",
          "in",
          "gb",
          "ca",
          "au",
          "de",
          "fr",
          "sg",
          "ae",
          "jp",
          "ad",
          "af",
          "ag",
          "al",
          "am",
          "ao",
          "ar",
          "at",
          "aw",
          "az",
          "ba",
          "bb",
          "bd",
          "be",
          "bf",
          "bg",
          "bh",
          "bi",
          "bj",
          "bn",
          "bo",
          "br",
          "bs",
          "bw",
          "by",
          "bz",
          "cd",
          "cg",
          "ch",
          "ci",
          "cl",
          "cm",
          "cn",
          "co",
          "cr",
          "cu",
          "cv",
          "cy",
          "cz",
          "dk",
          "do",
          "dz",
          "ec",
          "ee",
          "eg",
          "es",
          "et",
          "fi",
          "fj",
          "fm",
          "fo",
          "ga",
          "gd",
          "ge",
          "gf",
          "gg",
          "gh",
          "gm",
          "gp",
          "gq",
          "gr",
          "gt",
          "gu",
          "gy",
          "hk",
          "hn",
          "hr",
          "ht",
          "hu",
          "id",
          "ie",
          "il",
          "iq",
          "ir",
          "is",
          "it",
          "jm",
          "jo",
          "ke",
          "kg",
          "kh",
          "km",
          "kn",
          "kr",
          "kw",
          "ky",
          "kz",
          "la",
          "lb",
          "lc",
          "lk",
          "lr",
          "ls",
          "lt",
          "lu",
          "lv",
          "ly",
          "ma",
          "md",
          "me",
          "mg",
          "mk",
          "ml",
          "mm",
          "mn",
          "mo",
          "mp",
          "mq",
          "mr",
          "mt",
          "mu",
          "mv",
          "mw",
          "mx",
          "my",
          "mz",
          "na",
          "nc",
          "ne",
          "ng",
          "ni",
          "nl",
          "no",
          "np",
          "nz",
          "om",
          "pa",
          "pe",
          "pf",
          "pg",
          "ph",
          "pk",
          "pl",
          "pr",
          "ps",
          "pt",
          "pw",
          "py",
          "qa",
          "re",
          "ro",
          "rs",
          "ru",
          "rw",
          "sa",
          "sb",
          "sd",
          "se",
          "si",
          "sk",
          "sl",
          "sn",
          "so",
          "sr",
          "st",
          "sv",
          "sy",
          "sz",
          "td",
          "tg",
          "th",
          "tj",
          "tl",
          "tn",
          "to",
          "tr",
          "tt",
          "tw",
          "tz",
          "ua",
          "ug",
          "uy",
          "uz",
          "vc",
          "ve",
          "vg",
          "vi",
          "vn",
          "vu",
          "ye",
          "za",
          "zm",
          "zw"
        ],
        "default": "us"
      },
      "Locale": {
        "type": "string",
        "description": "A language-region tag, `xx-yy`.",
        "pattern": "^[A-Za-z]{2}-[A-Za-z]{2}$",
        "examples": [
          "en-us",
          "en-gb",
          "de-de"
        ]
      },
      "SafeSearch": {
        "type": "string",
        "enum": [
          "off",
          "moderate",
          "strict"
        ],
        "default": "off"
      },
      "QueryStatus": {
        "type": "string",
        "enum": [
          "ok",
          "error"
        ]
      },
      "ErrorCode": {
        "type": "string",
        "description": "Every code the API emits.\n- `invalid_request` — validation failed; `issues` lists the fields.\n- `unsupported_geo` — `geo` is not supported; `details` lists the supported codes.\n- `unsupported_parameter` — the target cannot serve `page`, `num` or `safe` as sent.\n- `unauthorized` — no accepted credential.\n- `not_found` — unknown route, or an API key id not on this account.\n- `rate_limited` — per-minute limit spent.\n- `quota_exceeded` — the period's quota and the credit balance are both spent. Not charged.\n- `upstream_error` — the search provider failed. Charged.\n- `upstream_timeout` — the search provider did not answer in time. Charged.\n- `no_subscription` — a plan change or a credit-pack purchase was asked for on an account with no active subscription.\n- `plan_unchanged` — a plan change was asked for on the plan the account is already on.\n- `billing_unavailable` — purchases are closed on this deployment: either it is not wired to Polar, or direct checkout is switched off while the same plans are sold on RapidAPI.\n- `internal_error` — a fault on our side. Not charged.\n",
        "enum": [
          "invalid_request",
          "unsupported_geo",
          "unsupported_parameter",
          "unauthorized",
          "not_found",
          "rate_limited",
          "quota_exceeded",
          "upstream_error",
          "upstream_timeout",
          "no_subscription",
          "plan_unchanged",
          "billing_unavailable",
          "internal_error"
        ]
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "The shape of every error response.",
        "required": [
          "error",
          "message",
          "request_id"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "type": "string",
            "description": "Human-readable, safe to show to an end user."
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "Same value as the `X-Request-Id` header."
          },
          "details": {
            "type": "array",
            "description": "On `unsupported_geo` only, the supported country codes.",
            "items": {
              "$ref": "#/components/schemas/Geo"
            }
          },
          "issues": {
            "type": "array",
            "description": "On `invalid_request` from a validator, one entry per failed field.",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Dotted path of the field. Empty for the whole input."
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "QuotaExceededEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorEnvelope"
          },
          {
            "type": "object",
            "description": "The `402 quota_exceeded` body — the error envelope plus where the account stands.",
            "required": [
              "plan",
              "quota",
              "credits_used",
              "remaining",
              "balance",
              "resets_at"
            ],
            "properties": {
              "plan": {
                "$ref": "#/components/schemas/PlanId"
              },
              "quota": {
                "type": "integer",
                "description": "Requests the quota allows — this billing cycle on a paid plan, for life on the trial."
              },
              "credits_used": {
                "type": "integer",
                "description": "Credits spent inside that quota."
              },
              "remaining": {
                "type": "integer",
                "minimum": 0,
                "description": "What is left of the period's quota. `0` when it is spent; above 0 only when a batch asked for more than `remaining` + `balance`."
              },
              "balance": {
                "type": "integer",
                "minimum": 0,
                "description": "Pack credits left. `0` alongside `remaining` `0` is what makes this a 402."
              },
              "resets_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "When the quota resets — the end of the subscription's billing cycle, `00:00:00Z` on the 1st for an account with no subscription cycle, or `null` on the trial, which never resets."
              }
            }
          }
        ]
      },
      "OrganicResult": {
        "type": "object",
        "description": "One organic result. `x-hub-fields` is the flat row every marketplace wrapper exposes: these organic fields plus the request echo (`query`, `target`, `geo`, `locale`, `page`), with `request_id` taken from the response `id`. It is paired with the fixtures in `docs/api/fixtures/`.",
        "x-hub-fields": [
          "position",
          "title",
          "url",
          "domain",
          "snippet",
          "query",
          "target",
          "geo",
          "locale",
          "page",
          "request_id"
        ],
        "required": [
          "position",
          "title",
          "url",
          "domain",
          "snippet"
        ],
        "properties": {
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "1-based rank within the answered page, after de-duplication."
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "domain": {
            "type": "string",
            "description": "The registrable domain of `url` (`example.co.uk`), or the hostname when it has no public suffix."
          },
          "snippet": {
            "type": "string",
            "description": "The engine's description text. Empty when the engine gave none."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "id",
          "target",
          "query",
          "geo",
          "locale",
          "page",
          "results"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The query's id in the log. `qry_` plus 32 hex characters.",
            "pattern": "^qry_[0-9a-f]{32}$"
          },
          "target": {
            "$ref": "#/components/schemas/Target"
          },
          "query": {
            "type": "string",
            "description": "The query as run, after whitespace normalisation."
          },
          "geo": {
            "$ref": "#/components/schemas/Geo"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "results": {
            "type": "object",
            "required": [
              "organic"
            ],
            "properties": {
              "organic": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrganicResult"
                }
              }
            }
          }
        }
      },
      "BulkQueryRow": {
        "description": "A bare query string, or an object naming the query and any per-row overrides. Unknown keys are ignored.",
        "oneOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 400
          },
          {
            "type": "object",
            "required": [
              "query"
            ],
            "properties": {
              "query": {
                "type": "string",
                "minLength": 1,
                "maxLength": 400
              },
              "target": {
                "$ref": "#/components/schemas/Target"
              },
              "geo": {
                "$ref": "#/components/schemas/Geo"
              },
              "locale": {
                "$ref": "#/components/schemas/Locale"
              },
              "page": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5,
                "default": 1
              },
              "num": {
                "type": "integer",
                "minimum": 1,
                "maximum": 20,
                "default": 10
              },
              "safe": {
                "$ref": "#/components/schemas/SafeSearch"
              },
              "source": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "Optional attribution label stored with the search (for example `zapier`, `make`, `n8n`). Stored truncated to 32 characters. Defaults to `api` when omitted. Not returned in the response.",
                "example": "zapier"
              }
            },
            "additionalProperties": true
          }
        ]
      },
      "BulkRequest": {
        "type": "object",
        "required": [
          "queries"
        ],
        "properties": {
          "target": {
            "$ref": "#/components/schemas/Target"
          },
          "geo": {
            "$ref": "#/components/schemas/Geo"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Optional attribution label stored with the search (for example `zapier`, `make`, `n8n`). Stored truncated to 32 characters. Defaults to `api` when omitted. Not returned in the response.",
            "example": "zapier"
          },
          "queries": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/BulkQueryRow"
            }
          }
        },
        "description": "`target`, `geo`, `locale` and `source` are defaults every row starts from; a row's own fields override them. The same rules as `GET /v1/query` apply to each row."
      },
      "BulkResultOk": {
        "type": "object",
        "description": "A served row, in the same shape as a `GET /v1/query` response plus `status`.",
        "required": [
          "status",
          "id",
          "target",
          "query",
          "geo",
          "locale",
          "page",
          "results"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          },
          "id": {
            "type": "string",
            "pattern": "^qry_[0-9a-f]{32}$"
          },
          "target": {
            "$ref": "#/components/schemas/Target"
          },
          "query": {
            "type": "string"
          },
          "geo": {
            "$ref": "#/components/schemas/Geo"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "results": {
            "type": "object",
            "required": [
              "organic"
            ],
            "properties": {
              "organic": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrganicResult"
                }
              }
            }
          }
        }
      },
      "BulkResultError": {
        "type": "object",
        "description": "A row that was refused or failed. Carries no `request_id` of its own; the batch's is in the `X-Request-Id` header.",
        "required": [
          "status",
          "error",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "error"
          },
          "error": {
            "type": "string",
            "description": "`invalid_request`, `unsupported_geo` and `unsupported_parameter` for a row that did not validate (not charged); `upstream_error` and `upstream_timeout` for a row that ran and failed (charged); `internal_error` for a fault on our side (not charged).",
            "enum": [
              "invalid_request",
              "unsupported_geo",
              "unsupported_parameter",
              "upstream_error",
              "upstream_timeout",
              "internal_error"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "BulkResult": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BulkResultOk"
          },
          {
            "$ref": "#/components/schemas/BulkResultError"
          }
        ],
        "discriminator": {
          "propertyName": "status",
          "mapping": {
            "ok": "#/components/schemas/BulkResultOk",
            "error": "#/components/schemas/BulkResultError"
          }
        }
      },
      "BulkResponse": {
        "type": "object",
        "required": [
          "batch_id",
          "total",
          "succeeded",
          "failed",
          "results"
        ],
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "`bat_` plus 32 hex characters. Every row's log entry carries it.",
            "pattern": "^bat_[0-9a-f]{32}$"
          },
          "total": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "succeeded": {
            "type": "integer",
            "minimum": 0
          },
          "failed": {
            "type": "integer",
            "minimum": 0
          },
          "results": {
            "type": "array",
            "description": "One entry per input row, in input order.",
            "items": {
              "$ref": "#/components/schemas/BulkResult"
            }
          }
        }
      },
      "UsageTotals": {
        "type": "object",
        "required": [
          "requests",
          "credits",
          "cache_hits",
          "errors",
          "avg_latency_ms"
        ],
        "properties": {
          "requests": {
            "type": "integer"
          },
          "credits": {
            "type": "integer"
          },
          "cache_hits": {
            "type": "integer"
          },
          "errors": {
            "type": "integer"
          },
          "avg_latency_ms": {
            "type": "integer",
            "description": "Rounded mean of `latency_ms` over the window's rows; 0 when there are none."
          }
        }
      },
      "UsageBucket": {
        "type": "object",
        "required": [
          "bucket",
          "requests",
          "credits",
          "cache_hits",
          "errors"
        ],
        "properties": {
          "bucket": {
            "type": "string",
            "description": "`YYYY-MM-DD` for daily, `YYYY-MM-DDTHH:00` for hourly. UTC."
          },
          "requests": {
            "type": "integer"
          },
          "credits": {
            "type": "integer"
          },
          "cache_hits": {
            "type": "integer"
          },
          "errors": {
            "type": "integer"
          }
        }
      },
      "UsageByKey": {
        "type": "object",
        "required": [
          "api_key_id",
          "label",
          "requests",
          "credits"
        ],
        "properties": {
          "api_key_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "`null` for calls made with the session cookie."
          },
          "label": {
            "type": "string",
            "description": "The key's name, `Dashboard` for session calls, `Deleted key` for a key row that no longer exists."
          },
          "requests": {
            "type": "integer"
          },
          "credits": {
            "type": "integer"
          }
        }
      },
      "UsageSummaryResponse": {
        "type": "object",
        "required": [
          "from",
          "to",
          "granularity",
          "api_key_id",
          "totals",
          "buckets",
          "by_key"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "The resolved lower bound."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "The resolved upper bound."
          },
          "granularity": {
            "type": "string",
            "enum": [
              "hourly",
              "daily"
            ]
          },
          "api_key_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The filter that was applied, or `null`."
          },
          "totals": {
            "$ref": "#/components/schemas/UsageTotals"
          },
          "buckets": {
            "type": "array",
            "description": "Ascending by `bucket`, one entry per bucket in the window, zero-filled.",
            "items": {
              "$ref": "#/components/schemas/UsageBucket"
            }
          },
          "by_key": {
            "type": "array",
            "description": "Descending by `requests`.",
            "items": {
              "$ref": "#/components/schemas/UsageByKey"
            }
          }
        }
      },
      "RecentQuery": {
        "type": "object",
        "required": [
          "id",
          "target",
          "query",
          "geo",
          "locale",
          "status",
          "cache_hit",
          "latency_ms",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "target": {
            "type": "string",
            "description": "Usually a `Target`; a refused request logs whatever was sent, clamped to 64 characters."
          },
          "query": {
            "type": "string"
          },
          "geo": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/QueryStatus"
          },
          "cache_hit": {
            "type": "boolean"
          },
          "latency_ms": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RecentQueriesResponse": {
        "type": "object",
        "required": [
          "queries"
        ],
        "properties": {
          "queries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecentQuery"
            }
          }
        }
      },
      "HistoryQuery": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RecentQuery"
          },
          {
            "type": "object",
            "required": [
              "api_key_id",
              "api_key_name",
              "batch_id",
              "request_id",
              "page",
              "num",
              "safe",
              "error_code",
              "http_status",
              "upstream_ms",
              "result_count",
              "credits"
            ],
            "properties": {
              "api_key_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "api_key_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The key's current name, `null` for a session call or a deleted key."
              },
              "batch_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Set for rows made through `POST /v1/bulk`."
              },
              "request_id": {
                "type": "string"
              },
              "page": {
                "type": "integer"
              },
              "num": {
                "type": "integer"
              },
              "safe": {
                "type": "string"
              },
              "error_code": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The `ErrorCode` answered, `null` on a served row."
              },
              "http_status": {
                "type": "integer"
              },
              "upstream_ms": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Time spent in the search provider, `null` unless the row was served."
              },
              "result_count": {
                "type": "integer"
              },
              "credits": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "QueryHistoryResponse": {
        "type": "object",
        "required": [
          "rows",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoryQuery"
            }
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "total": {
            "type": "integer",
            "description": "Rows matching the filters across all pages."
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "description": "A key as its owner sees it. The secret is never included.",
        "required": [
          "id",
          "name",
          "key_type",
          "prefix",
          "last4",
          "created_at",
          "last_used_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^key_[0-9a-f]{32}$"
          },
          "name": {
            "type": "string"
          },
          "key_type": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "prefix": {
            "type": "string",
            "description": "The first characters of the secret, enough to recognise it in a config file."
          },
          "last4": {
            "type": "string",
            "description": "The last four characters of the secret."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Updated at most once every five minutes of use."
          }
        }
      },
      "CreateApiKeyRequest": {
        "type": "object",
        "required": [
          "name",
          "key_type"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "A label. Trimmed."
          },
          "key_type": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "`live` keys get the `sk_live_` prefix, `test` keys get `sk_test_`. Both are held to the account plan's rate and spend the same quota."
          }
        }
      },
      "RenameApiKeyRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          }
        }
      },
      "ListApiKeysResponse": {
        "type": "object",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKey"
            }
          }
        }
      },
      "ApiKeyResponse": {
        "type": "object",
        "required": [
          "api_key"
        ],
        "properties": {
          "api_key": {
            "$ref": "#/components/schemas/ApiKey"
          }
        }
      },
      "MintedApiKeyResponse": {
        "type": "object",
        "required": [
          "key",
          "api_key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The plaintext secret. Shown once.",
            "pattern": "^sk_(live|test)_[A-Za-z0-9_-]{43}$"
          },
          "api_key": {
            "$ref": "#/components/schemas/ApiKey"
          }
        }
      },
      "PlanId": {
        "type": "string",
        "enum": [
          "trial",
          "starter",
          "growth",
          "business",
          "enterprise"
        ],
        "default": "trial"
      },
      "MeApiKey": {
        "type": "object",
        "description": "The API key that made the call.",
        "required": [
          "id",
          "label",
          "mode"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The key's id, as listed in the dashboard and by `GET /v1/api-keys`."
          },
          "label": {
            "type": "string",
            "description": "The name the key was given when it was created."
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "Whether this is an `sk_live_` or an `sk_test_` key."
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "email",
          "plan",
          "credits_available",
          "api_key"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "The account's email address. Empty for a marketplace subscriber."
          },
          "plan": {
            "$ref": "#/components/schemas/PlanId",
            "description": "The plan the account is on."
          },
          "credits_available": {
            "type": "integer",
            "minimum": 0,
            "description": "Credits the account can still spend — the period's remaining quota plus the credit-pack balance."
          },
          "api_key": {
            "description": "The calling API key. `null` for a session, marketplace or demo caller.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/MeApiKey"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CreditPackSize": {
        "type": "integer",
        "description": "The credit packs on offer. The same three sizes on every plan; only the price per credit changes.",
        "enum": [
          10000,
          50000,
          100000
        ]
      },
      "PlanQuotaPeriod": {
        "type": "string",
        "description": "What the plan's quota is measured over.\n- `month` — the subscription's billing cycle, renewing monthly on the day it started. An account with no subscription cycle behind its plan falls back to the calendar month in UTC, reset at `00:00:00Z` on the 1st. `period.end` and `X-Quota-Reset` carry the exact moment either way.\n- `lifetime` — counted from the account's first search and never reset. The trial only.\n",
        "enum": [
          "lifetime",
          "month"
        ]
      },
      "Plan": {
        "type": "object",
        "description": "One plan. Prices are US dollars per month, the same bought direct or through RapidAPI.",
        "required": [
          "id",
          "name",
          "rapidapi_slot",
          "price_usd",
          "monthly_quota",
          "quota_period",
          "recharge_per_request_usd",
          "concurrency",
          "rate_limit_per_minute",
          "recommended",
          "public"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PlanId"
          },
          "name": {
            "type": "string"
          },
          "rapidapi_slot": {
            "type": "string",
            "description": "The tier this plan is listed as on RapidAPI.",
            "enum": [
              "BASIC",
              "PRO",
              "ULTRA",
              "MEGA",
              "CUSTOM"
            ]
          },
          "price_usd": {
            "type": "number",
            "description": "US dollars per month. The same price on RapidAPI and direct."
          },
          "monthly_quota": {
            "type": "integer",
            "description": "Requests included per period — per billing cycle on a paid plan, or once for life on the trial."
          },
          "quota_period": {
            "$ref": "#/components/schemas/PlanQuotaPeriod"
          },
          "recharge_per_request_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "What one pack credit costs on this plan, and so what a credit pack is priced at. `null` on the trial, which cannot buy one. Quoted publicly per 1,000 — `0.0015` is $1.50 per 1,000 credits."
          },
          "concurrency": {
            "type": "integer",
            "description": "How many requests the plan runs at once, and how the limit is quoted publicly. Enforced as `concurrency × 60` requests per rolling minute."
          },
          "rate_limit_per_minute": {
            "type": "integer",
            "description": "The enforced rate for this plan's keys and MCP tokens. A dashboard session gets this or 120, whichever is higher."
          },
          "recommended": {
            "type": "boolean",
            "description": "True on the one plan the pricing page highlights."
          },
          "public": {
            "type": "boolean",
            "description": "Whether the plan is offered. False on the trial and on the plan a negotiated deal is put on, which is advertised as \"Custom\" instead."
          }
        }
      },
      "BillingUsage": {
        "type": "object",
        "required": [
          "credits_used",
          "quota",
          "remaining",
          "balance",
          "allowance",
          "quota_period"
        ],
        "properties": {
          "credits_used": {
            "type": "integer",
            "description": "Credits spent inside the current period."
          },
          "quota": {
            "type": "integer",
            "description": "Requests the period allows. On the trial this is what is left of the account's one-time grant — 0 for an address that already used a trial."
          },
          "remaining": {
            "type": "integer",
            "minimum": 0,
            "description": "What is left of the period's quota. Never below 0."
          },
          "balance": {
            "type": "integer",
            "minimum": 0,
            "description": "Pack credits on the account. Spent only once `remaining` is 0, and never expires."
          },
          "allowance": {
            "type": "integer",
            "minimum": 0,
            "description": "`remaining` + `balance`: everything the account may still spend before a 402."
          },
          "quota_period": {
            "$ref": "#/components/schemas/PlanQuotaPeriod"
          }
        }
      },
      "CreditPack": {
        "type": "object",
        "description": "One credit pack on offer, priced at the account's own plan rate.",
        "required": [
          "size",
          "price_usd"
        ],
        "properties": {
          "size": {
            "$ref": "#/components/schemas/CreditPackSize"
          },
          "price_usd": {
            "type": "number",
            "description": "What the pack costs, in US dollars. Polar takes the payment and issues the receipt."
          }
        }
      },
      "BillingPurchase": {
        "type": "object",
        "description": "One credit pack the account has bought.",
        "required": [
          "id",
          "plan",
          "credits",
          "amount_usd",
          "currency",
          "status",
          "paid_at",
          "refunded_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The Polar order id."
          },
          "plan": {
            "$ref": "#/components/schemas/PlanId"
          },
          "credits": {
            "type": "integer",
            "description": "Credits the pack carried. They are added to the balance in full when the order is paid."
          },
          "amount_usd": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "paid",
              "refunded"
            ],
            "description": "`refunded` once Polar reports the order refunded, at which point the credits are taken back off the balance, clamped at 0."
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "refunded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "BillingCredits": {
        "type": "object",
        "description": "Credit packs — the balance, what is on offer and what has been bought.",
        "required": [
          "balance",
          "packs",
          "purchases"
        ],
        "properties": {
          "balance": {
            "type": "integer",
            "minimum": 0,
            "description": "Pack credits left. Account-wide: it never expires and survives the subscription that bought it, so it is present even with no subscription."
          },
          "packs": {
            "type": "array",
            "description": "The packs the account may buy right now, priced off its own plan, smallest first. Empty on the trial, which cannot buy one.",
            "items": {
              "$ref": "#/components/schemas/CreditPack"
            }
          },
          "purchases": {
            "type": "array",
            "description": "The last ten purchases, newest first.",
            "items": {
              "$ref": "#/components/schemas/BillingPurchase"
            }
          }
        }
      },
      "BillingSubscription": {
        "type": "object",
        "description": "The Polar subscription behind a paid plan.",
        "required": [
          "subscription_id",
          "plan",
          "status",
          "current_period_start",
          "current_period_end",
          "cancel_at_period_end",
          "ends_at"
        ],
        "properties": {
          "subscription_id": {
            "type": "string"
          },
          "plan": {
            "type": "string",
            "enum": [
              "starter",
              "growth",
              "business",
              "enterprise"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "incomplete",
              "incomplete_expired",
              "trialing",
              "active",
              "past_due",
              "canceled",
              "unpaid"
            ],
            "description": "Polar's own status. `active`, `trialing` and `past_due` still entitle the plan."
          },
          "current_period_start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "First instant of the billing period. This is also the window the quota is measured over."
          },
          "current_period_end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cancel_at_period_end": {
            "type": "boolean",
            "description": "True once cancelled in the portal. Access runs to `ends_at`; the plan steps down when the subscription actually ends."
          },
          "ends_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": [
          "plan"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "starter",
              "growth",
              "business"
            ],
            "description": "The plan to buy. Enterprise is quoted by hand and is not self-served."
          }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Polar's hosted checkout. Redirect the browser to it."
          }
        }
      },
      "CreditsCheckoutRequest": {
        "type": "object",
        "required": [
          "size"
        ],
        "properties": {
          "size": {
            "$ref": "#/components/schemas/CreditPackSize"
          }
        }
      },
      "CreditsCheckoutResponse": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Polar's hosted one-time checkout for the pack. Redirect the browser to it."
          }
        }
      },
      "PortalResponse": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Polar's hosted customer portal. Short-lived and single-customer."
          }
        }
      },
      "PlanChangeRequest": {
        "type": "object",
        "required": [
          "plan"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "starter",
              "growth",
              "business"
            ]
          }
        }
      },
      "PlanChangeResponse": {
        "type": "object",
        "required": [
          "subscription",
          "proration"
        ],
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/BillingSubscription"
          },
          "proration": {
            "type": "string",
            "enum": [
              "invoice",
              "next_period"
            ],
            "description": "`invoice` on an upgrade — the difference is charged now and the new quota is live immediately. `next_period` on a downgrade — the paid-for period runs out first."
          }
        }
      },
      "BillingSummaryResponse": {
        "type": "object",
        "required": [
          "plan",
          "period",
          "usage",
          "subscription",
          "credits",
          "plans",
          "custom",
          "upgrade",
          "checkout"
        ],
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "period": {
            "type": "object",
            "description": "The window the usage is measured over, UTC.",
            "required": [
              "start",
              "end"
            ],
            "properties": {
              "start": {
                "type": "string",
                "format": "date-time",
                "description": "First instant of the window, inclusive. The epoch on a lifetime quota."
              },
              "end": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "First instant of the next window, exclusive, and when the quota resets. `null` on a lifetime quota, which never rolls over."
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/BillingUsage"
          },
          "subscription": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BillingSubscription"
              },
              {
                "type": "null"
              }
            ],
            "description": "The subscription behind the plan, or `null` on an account that has never bought one."
          },
          "credits": {
            "$ref": "#/components/schemas/BillingCredits"
          },
          "plans": {
            "type": "array",
            "description": "The plans on offer, cheapest first, plus the account's own when it is on one that is not offered.",
            "items": {
              "$ref": "#/components/schemas/Plan"
            }
          },
          "custom": {
            "type": "object",
            "description": "Where to write for volume, concurrency or contract terms above the listed plans.",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              }
            }
          },
          "upgrade": {
            "type": "object",
            "description": "How to change plan while dashboard checkout is being built.",
            "required": [
              "email",
              "rapidapi_url"
            ],
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              },
              "rapidapi_url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "checkout": {
            "type": "object",
            "description": "Whether a purchase can be started here, and where the same plans are sold while it cannot.",
            "required": [
              "enabled",
              "rapidapi_url"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "`false` ⇒ the two checkouts and the plan change answer `503 billing_unavailable`."
              },
              "rapidapi_url": {
                "type": "string",
                "format": "uri",
                "description": "The marketplace listing selling the same plans at the same price."
              }
            }
          }
        }
      }
    }
  }
}