API Overview

Welcome to the fetchSERP API documentation. All reference pages you see in this section are auto-generated from our openapi.json specification, so they’re always in sync with the latest version of the API.

Authentication

Every request must include your API token in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

• Tokens are created in the dashboard.
• If a request is sent without a token or with an invalid token, the API responds with 401 Unauthorized.

Google SERP options

Google results on /api/v1/serp, /api/v1/serp_html, /api/v1/serp_text and /api/v1/ranking are rendered in a real browser, so they take a few extra, Google-only parameters:

Parameter	What it does
`device`	`desktop` (default) or `mobile`. Mobile results come from a phone profile and are collected with Google’s “More results” loading rather than numbered pages.
`location`	Where the search is made from: `lat,lng` in decimal degrees (for example `40.6782,-73.9442`), or a place name — a city, neighborhood, county, state or postal code (`Brooklyn, NY`, `Austin TX`, `11216`, `SW1A 1AA, UK`). The browser session is placed there, so local results and the SERP footer reflect that location. Names come back resolved in the response’s `location` block (`name`, `type`, coordinates, `timezone`); find valid names with `GET /api/v1/locations?q=brook` (free). A named location sets its own time zone; for coordinates, pass `timezone` (an IANA id such as `America/New_York`).
`resolve_urls`	Default `true`. Google’s `google.com/goto` redirect links are followed to their destination; each result reports `url_resolved` and `url_source`, and the response carries a `resolution` summary.
`strict`	Default `false`. Return `422` instead of results when the page looks poisoned.
`samples`	`/serp` only. Take 1-5 independent captures of page 1 and return how often each domain appears across them (`distribution`).
`max_resamples`	Extra captures (0-3) taken when page 1 looks poisoned; the best one is returned. Each is a fresh browser identity, so it can add tens of seconds.

Every Google page is scored for poisoning and the score comes back in quality (score, flags, suspected_poisoned). When a later page of a multi-page request fails, the pages that did load are returned with a warnings array instead of an error; only a request with no results at all fails. The full parameter and response schemas are on each endpoint’s page.

Rate Limits

We allow up to 600 requests per minute per account (aggregated across all endpoints). When the limit is exceeded the API responds with 429 Too Many Requests plus a Retry-After header indicating how many seconds to wait before retrying. If you need higher throughput, please contact support and we’ll bump the limit for your workspace.

Need a quick start? Head over to the Quickstart guide or explore a specific endpoint in the sidebar.

API Documentation

API Endpoints

Authentication

Google SERP options

Rate Limits

​Authentication

​Google SERP options

​Rate Limits

Authentication

Google SERP options

Rate Limits