Skip to content
SerpResultAPI

Run one search

GET
/v1/query
curl --request GET \
  --url 'https://api.serpresult.com/v1/query?query=serp%20api&target=google_search&geo=us&locale=en-us&page=1&num=10&safe=off&source=zapier' \
  --header 'Authorization: Bearer <token>'

Runs a single search against the requested target and answers its organic results in rank order. Costs one credit on every 200, 502 and 504.

Per-target rules, each violation answering 400 unsupported_parameter: google_search and brave_search accept pages 1–5 and num 1–20; bing_search serves page=1 only; duckduckgo_search serves page=1 only, caps num at 10 and takes no safe but off; yahoo_search serves page=1 only and caps num at 10; yandex_search accepts pages 1–5, caps num at 10 and takes no safe but off.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
query
required
string
>= 1 characters <= 400 characters

The search terms. Surrounding whitespace is trimmed and runs of whitespace collapse to one space before the length check.

Example
serp api
target

The engine to search.

  • google_search: pages 1–5, num up to 20, safe search supported.
  • bing_search: page 1 only, num up to 20, safe search supported.
  • duckduckgo_search: page 1 only, num up to 10, no safe search.
  • yahoo_search: page 1 only, num up to 10, safe search supported.
  • brave_search: pages 1–5, num up to 20, safe search supported.
  • yandex_search: pages 1–5, num up to 10, no safe search.
string
default: google_search
Allowed values: google_search bing_search duckduckgo_search yahoo_search brave_search yandex_search

Which engine to search. Each one caps page, num and safe differently; see the Target schema.

geo

A supported country, as an ISO 3166-1 alpha-2 code. Results are localized to this country, the same ones a user searching there would see, and the code also picks the default locale.

string
default: us
Allowed values: 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

The country the results are localized to. Also picks the default locale. An unsupported value answers 400 unsupported_geo.

locale

A language-region tag, xx-yy.

string
/^[A-Za-z]{2}-[A-Za-z]{2}$/

Interface language and region as xx-yy, case-insensitive, stored lowercase. Every supported geo carries its own default — us is en-us, jp is ja-jp, br is pt-br — and omitting locale takes it. The docs list the default for each country under “Targets and geo”.

page
integer
default: 1 >= 1 <= 5

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.

num
integer
default: 10 >= 1 <= 20

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.

safe
string
default: off
Allowed values: off moderate strict

Safe-search level. Supported by every target but duckduckgo_search and yandex_search, which answer 400 unsupported_parameter for anything but off.

source
string
>= 1 characters <= 256 characters

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

Responses

Section titled “Responses”

200

Section titled “200”

The search ran. results.organic may be empty when the engine returned nothing.

Media typeapplication/json
object
id
required

The query’s id in the log. qry_ plus 32 hex characters.

string
/^qry_[0-9a-f]{32}$/
target
required

The engine to search.

  • google_search: pages 1–5, num up to 20, safe search supported.
  • bing_search: page 1 only, num up to 20, safe search supported.
  • duckduckgo_search: page 1 only, num up to 10, no safe search.
  • yahoo_search: page 1 only, num up to 10, safe search supported.
  • brave_search: pages 1–5, num up to 20, safe search supported.
  • yandex_search: pages 1–5, num up to 10, no safe search.
string
default: google_search
Allowed values: google_search bing_search duckduckgo_search yahoo_search brave_search yandex_search
query
required

The query as run, after whitespace normalisation.

string
geo
required

A supported country, as an ISO 3166-1 alpha-2 code. Results are localized to this country, the same ones a user searching there would see, and the code also picks the default locale.

string
default: us
Allowed values: 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
locale
required

A language-region tag, xx-yy.

string
/^[A-Za-z]{2}-[A-Za-z]{2}$/
page
required
integer
>= 1
results
required
object
organic
required
Array<object>

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/.

object
position
required

1-based rank within the answered page, after de-duplication.

integer
>= 1
title
required
string
url
required
string format: uri
domain
required

The registrable domain of url (example.co.uk), or the hostname when it has no public suffix.

string
snippet
required

The engine’s description text. Empty when the engine gave none.

string
Examples

google_search, geo=us, num=3

{
  "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."
      }
    ]
  }
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-Credits-Used
integer

Credits charged by this response.

X-RateLimit-Limit
integer

Requests allowed per rolling 60-second window for this credential.

X-RateLimit-Remaining
integer

Requests left in the window, after this one.

X-RateLimit-Reset
integer

Unix time (seconds) at which the current window ends.

X-Quota-Limit
integer

Requests the account’s quota allows — this billing cycle on a paid plan, for life on the trial.

X-Quota-Used
integer

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.

X-Quota-Remaining
integer

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.

X-Credits-Balance
integer

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.

X-Quota-Reset
integer

Unix time (seconds) at which the quota resets: the end of the subscription’s billing cycle, or 00:00:00Z on the 1st for an account with no subscription cycle behind its plan. This header is the exact moment — do not derive it from a calendar. Absent on the trial, whose 100 requests never reset.

400

Section titled “400”

The request could not be run. error says why:

  • invalid_request — a parameter failed validation; issues lists each field.
  • unsupported_geo — geo is not a supported country; details lists the supported codes.
  • 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).

No credit is charged.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Examples

bing_search with page=2

{
  "error": "unsupported_parameter",
  "message": "page is not supported for bing_search",
  "request_id": "ff42f055-9ddf-4312-b524-74ce85151640"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-RateLimit-Limit
integer

Requests allowed per rolling 60-second window for this credential.

X-RateLimit-Remaining
integer

Requests left in the window, after this one.

X-RateLimit-Reset
integer

Unix time (seconds) at which the current window ends.

X-Quota-Limit
integer

Requests the account’s quota allows — this billing cycle on a paid plan, for life on the trial.

X-Quota-Used
integer

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.

X-Quota-Remaining
integer

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.

X-Credits-Balance
integer

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.

X-Quota-Reset
integer

Unix time (seconds) at which the quota resets: the end of the subscription’s billing cycle, or 00:00:00Z on the 1st for an account with no subscription cycle behind its plan. This header is the exact moment — do not derive it from a calendar. Absent on the trial, whose 100 requests never reset.

401

Section titled “401”

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.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Example
{
  "error": "unauthorized",
  "message": "API key is not valid.",
  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

402

Section titled “402”

The period’s quota AND the credit balance are both spent (quota_exceeded). Every plan is hard-limited, so this is the answer on any of them. Nothing ran, nothing was logged and nothing was charged. On POST /v1/bulk this is also the answer to a batch carrying more rows than remaining + balance, refused whole before any row runs. On a paid plan the way out is a credit pack; on the trial it is a paid plan, since a pack is priced off a subscription. resets_at is null on the trial, whose requests never come back.

Media typeapplication/json
object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
plan
required
string
default: trial
Allowed values: trial starter growth business enterprise
quota
required

Requests the quota allows — this billing cycle on a paid plan, for life on the trial.

integer
credits_used
required

Credits spent inside that quota.

integer
remaining
required

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.

integer
balance
required

Pack credits left. 0 alongside remaining 0 is what makes this a 402.

integer
resets_at
required

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.

string | null format: date-time
Examples

The trial's 100 requests are spent

{
  "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
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-Quota-Limit
integer

Requests the account’s quota allows — this billing cycle on a paid plan, for life on the trial.

X-Quota-Used
integer

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.

X-Quota-Remaining
integer

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.

X-Credits-Balance
integer

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.

X-Quota-Reset
integer

Unix time (seconds) at which the quota resets: the end of the subscription’s billing cycle, or 00:00:00Z on the 1st for an account with no subscription cycle behind its plan. This header is the exact moment — do not derive it from a calendar. Absent on the trial, whose 100 requests never reset.

429

Section titled “429”

The credential’s per-minute limit is spent (rate_limited). Wait Retry-After seconds.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Example
{
  "error": "rate_limited",
  "message": "Rate limit of 20 requests per minute exceeded. Retry in 37 seconds.",
  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-RateLimit-Limit
integer

Requests allowed per rolling 60-second window for this credential.

X-RateLimit-Remaining
integer

Requests left in the window, after this one.

X-RateLimit-Reset
integer

Unix time (seconds) at which the current window ends.

Retry-After
integer
>= 1

Whole seconds to wait before retrying. Never below 1.

500

Section titled “500”

Something failed on our side (internal_error). The detail is in our logs under request_id. Nothing is charged.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Example
{
  "error": "internal_error",
  "message": "The request could not be completed.",
  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

502

Section titled “502”

The search provider could not be reached or answered with an unusable payload (upstream_error). One credit is charged.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Example
{
  "error": "upstream_error",
  "message": "The upstream search provider could not be reached. Try again.",
  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-Credits-Used
integer

Credits charged by this response.

X-RateLimit-Limit
integer

Requests allowed per rolling 60-second window for this credential.

X-RateLimit-Remaining
integer

Requests left in the window, after this one.

X-RateLimit-Reset
integer

Unix time (seconds) at which the current window ends.

X-Quota-Limit
integer

Requests the account’s quota allows — this billing cycle on a paid plan, for life on the trial.

X-Quota-Used
integer

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.

X-Quota-Remaining
integer

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.

X-Credits-Balance
integer

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.

X-Quota-Reset
integer

Unix time (seconds) at which the quota resets: the end of the subscription’s billing cycle, or 00:00:00Z on the 1st for an account with no subscription cycle behind its plan. This header is the exact moment — do not derive it from a calendar. Absent on the trial, whose 100 requests never reset.

504

Section titled “504”

The search provider did not answer within the 15-second budget (upstream_timeout). One credit is charged.

Media typeapplication/json

The shape of every error response.

object
error
required

Every code the API emits.

  • invalid_request — validation failed; issues lists the fields.
  • unsupported_geo — geo is not supported; details lists the supported codes.
  • unsupported_parameter — the target cannot serve page, num or safe as sent.
  • unauthorized — no accepted credential.
  • not_found — unknown route, or an API key id not on this account.
  • rate_limited — per-minute limit spent.
  • quota_exceeded — the period’s quota and the credit balance are both spent. Not charged.
  • upstream_error — the search provider failed. Charged.
  • upstream_timeout — the search provider did not answer in time. Charged.
  • no_subscription — a plan change or a credit-pack purchase was asked for on an account with no active subscription.
  • plan_unchanged — a plan change was asked for on the plan the account is already on.
  • 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.
  • internal_error — a fault on our side. Not charged.
string
Allowed values: 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
message
required

Human-readable, safe to show to an end user.

string
request_id
required

Same value as the X-Request-Id header.

string format: uuid
details

On unsupported_geo only, the supported country codes.

Array<string>
Allowed values: 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
issues

On invalid_request from a validator, one entry per failed field.

Array<object>
object
field
required

Dotted path of the field. Empty for the whole input.

string
message
required
string
Example
{
  "error": "upstream_timeout",
  "message": "The upstream search provider did not answer in time. Try again.",
  "request_id": "7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90"
}

Headers

Section titled “Headers”
X-Request-Id
string format: uuid

The id of this request, identical to request_id in any error body. Quote it in a support request.

X-Credits-Used
integer

Credits charged by this response.

X-RateLimit-Limit
integer

Requests allowed per rolling 60-second window for this credential.

X-RateLimit-Remaining
integer

Requests left in the window, after this one.

X-RateLimit-Reset
integer

Unix time (seconds) at which the current window ends.

X-Quota-Limit
integer

Requests the account’s quota allows — this billing cycle on a paid plan, for life on the trial.

X-Quota-Used
integer

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.

X-Quota-Remaining
integer

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.

X-Credits-Balance
integer

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.

X-Quota-Reset
integer

Unix time (seconds) at which the quota resets: the end of the subscription’s billing cycle, or 00:00:00Z on the 1st for an account with no subscription cycle behind its plan. This header is the exact moment — do not derive it from a calendar. Absent on the trial, whose 100 requests never reset.