serpfast API reference

The serpfast API returns live search engine results as JSON. It has four endpoints that share the same authentication, response envelope and credit model. All endpoints use GET and live under:

Base URL

https://serpfast.com/api/v1

Authentication

Create a key in the dashboard. Keys start with sf_live_ and are shown once, so store them in an environment variable. Send the key in any of these ways:

Header Authorization: Bearer sf_live_... (recommended)
Header X-API-Key: sf_live_...
Query parameter api_key=sf_live_... (convenient for testing; avoid in browser code because URLs end up in logs)

Web search

GET/api/v1/search

Returns organic results and, on the first page, related searches.

Parameter	Type	Description
`q`required	string	Search query, 1 to 400 characters. Search operators such as site:, quotes and - work.
`gl`	string	Country, ISO 3166-1 alpha-2 code (US, GB, VN, BR, JP...). Default: US.
`hl`	string	Language code (en, vi, pt, ja, zh-hans...). Default: the country's main language.
`num`	integer	Results per call, 10 to 100. Default 10. Costs 1 credit per 10 results.
`page`	integer	Page number of size num, 1 to 50. Default 1. Positions continue across pages (page 2 of num=10 starts at 11).
`time`	string	Freshness filter: d (past day), w (week), m (month), y (year).
`related`	boolean	1 or true to include related_searches. Default off.

Response fields

Parameter	Type	Description
`organic_results[].position`	integer	1-based rank in the results.
`organic_results[].title`	string	Result title.
`organic_results[].link`	string	Destination URL (click-tracking redirects are decoded).
`organic_results[].displayed_link`	string	The breadcrumb-style URL shown in the results.
`organic_results[].source`	string \| null	Site name or domain shown in the results.
`organic_results[].snippet`	string	Description text, without the date.
`organic_results[].date`	string \| null	Publication date as displayed in the results, in the market's language.
`related_searches[].query`	string	Related search suggested by the search engine.
`search_information.total_results`	integer \| null	Estimated result count.
`search_information.pages_served`	integer	Results pages of 10 returned. Can be lower than num / 10 when deeper pages are unavailable; you are charged only for these.

GET /api/v1/search?q=best+running+shoes&related=1

{
  "search_metadata": {
    "id": "5f0c9a52-3c1e-4c7b-9d0e-2b8a51f4e7a1",
    "status": "success",
    "endpoint": "web",
    "credits_used": 1,
    "credits_remaining": 999,
    "created_at": "2026-10-13T09:20:11.482Z"
  },
  "search_parameters": { "q": "best running shoes", "gl": "US", "hl": "en", "page": 1, "num": 10, "time": null },
  "search_information": { "total_results": 23800, "time_taken_ms": 592 },
  "organic_results": [
    {
      "position": 1,
      "title": "The 15 Best Running Shoes of 2026, Tested by Runner’s World",
      "link": "https://www.runnersworld.com/gear/a19663621/best-running-shoes/",
      "displayed_link": "https://www.runnersworld.com › gear › best-running-shoes",
      "source": "runnersworld.com",
      "snippet": "Find the best running shoes of 2026, including Runner’s World-tested picks from Adidas, Brooks, New Balance, Nike, …",
      "date": "Aug 3, 2026"
    }
  ],
  "related_searches": [{ "query": "best running shoes for women 2026" }]
}

Image search

GET/api/v1/images

Parameter	Type	Description
`q`required	string	Search query, 1 to 400 characters. Search operators such as site:, quotes and - work.
`gl`	string	Country, ISO 3166-1 alpha-2 code (US, GB, VN, BR, JP...). Default: US.
`hl`	string	Language code (en, vi, pt, ja, zh-hans...). Default: the country's main language.
`num`	integer	Images per call, 1 to 150. Default 35. Costs 1 credit.
`page`	integer	Page number of size num, 1 to 50. Default 1.

GET /api/v1/images?q=red+sports+car

{
  "search_metadata": { "...": "..." },
  "search_parameters": { "q": "red sports car", "gl": "US", "hl": "en", "page": 1, "num": 35 },
  "images_results": [
    {
      "position": 1,
      "title": "Red Sports Cars",
      "original": "https://jooinn.com/images/red-sports-car-10.jpg",
      "thumbnail": "https://images.example-cdn.net/th/OIP.LWFRcB6G5rIZalZmOP10PwHaEW",
      "source_page": "https://ar.inspiredpencil.com/pictures-2023/red-sports-cars",
      "source": "ar.inspiredpencil.com",
      "width": 7139,
      "height": 4190
    }
  ]
}

Autocomplete

GET/api/v1/autocomplete

Returns autocomplete query suggestions for a prefix. Costs 1 credit.

Parameter	Type	Description
`q`required	string	Search query, 1 to 400 characters. Search operators such as site:, quotes and - work.
`gl`	string	Country, ISO 3166-1 alpha-2 code (US, GB, VN, BR, JP...). Default: US.
`hl`	string	Language code (en, vi, pt, ja, zh-hans...). Default: the country's main language.

GET /api/v1/autocomplete?q=cách+nấu+phở&gl=VN

{
  "search_metadata": { "...": "..." },
  "search_parameters": { "q": "cách nấu phở", "gl": "VN", "hl": "vi" },
  "suggestions": [
    { "value": "cách nấu phở bò" },
    { "value": "cách nấu phở bò miền bắc" },
    { "value": "cách nấu phở gà" }
  ]
}

Rank check

GET/api/v1/rank

Scans the top depth results for a domain. Subdomains match too: target=example.com matches blog.example.com. rank is null when the domain is not found.

Parameter	Type	Description
`q`required	string	Search query, 1 to 400 characters. Search operators such as site:, quotes and - work.
`gl`	string	Country, ISO 3166-1 alpha-2 code (US, GB, VN, BR, JP...). Default: US.
`hl`	string	Language code (en, vi, pt, ja, zh-hans...). Default: the country's main language.
`target`required	string	Domain or URL to look for, e.g. example.com.
`depth`	integer	Results to scan, 10 to 100. Default 50. Costs 1 credit per 10 results.

GET /api/v1/rank?q=best+running+shoes&target=rtings.com

{
  "search_metadata": { "...": "..." },
  "search_parameters": { "q": "best running shoes", "target": "rtings.com", "gl": "US", "hl": "en", "depth": 50 },
  "rank": { "position": 7, "title": "The 5 Best Running Shoes of 2026 - RTINGS.com", "link": "https://www.rtings.com/running-shoes/reviews/best/running" },
  "matches": [
    { "position": 7, "title": "The 5 Best Running Shoes of 2026 - RTINGS.com", "link": "https://www.rtings.com/running-shoes/reviews/best/running" }
  ],
  "scanned": 50,
  "top_results": [ { "position": 1, "title": "...", "link": "...", "...": "..." } ],
  "time_taken_ms": 1710
}

Platform APIs

Besides the endpoints above, the API serves data from other platforms, grouped by platform, at /api/v1/{platform}/{endpoint}. They share authentication, the search_metadata envelope, rate limits and errors with the rest of the API, and each request costs 1 credit. Parameters are checked before anything is charged; an unknown parameter is refused rather than ignored.

Google29 Bing6 YouTube4 Yahoo3 DuckDuckGo2 Brave1 Baidu1 Yandex2 Naver1 Airbnb1 AliExpress2 Amazon2 Apartments.com2 Apple5 Jobs by Ashby1 Best Buy2 Bluesky3 eBay2 Etsy1 Eventbrite1 Facebook7 GitHub5 Greenhouse2 Hacker News3 Home Depot2 Homes.com2 IKEA2 Indeed1 Instagram4 Kroger2 Levels.fyi1 Lever1 LinkedIn4 npm2 Pinterest1 Product Hunt1 PyPI1 Realtor.com2 Reddit3 Redfin1 Remote OK1 Shopify1 SoundCloud1 Spotify1 Sprouts2 Stack Overflow4 Steam2 Substack1 Target2 Telegram1 TikTok17 Tripadvisor3 Walmart1 Wayfair2 Web2 Whole Foods2 Wikipedia2 X5 Yelp2 Zillow2

When a source is down the request is retried on another one where possible. If only results unrelated to the query can be found, they are returned with search_metadata.warning: "results_may_be_unrelated" and the request is not charged. A search that returns no results at all is not charged either.

Credits

One credit buys one results page of 10 organic results. Every response includes search_metadata.credits_used and credits_remaining, also sent as the X-Credits-Used and X-Credits-Remaining headers. When a request asks for several pages (num above 10, or a rank check) and only some of them can be retrieved, you are charged for the pages returned and the rest is refunded right away.

Endpoint	Cost
`/search`	ceil(num / 10): num=10 costs 1, num=100 costs 10
`/rank`	ceil(depth / 10): depth=50 costs 5
`/images`	1
`/autocomplete`	1
Platform APIs (`/{platform}/{endpoint}`)	1

Requests that fail because the search engine could not be reached are refunded automatically.

Errors

Errors use standard HTTP status codes and a JSON body with a machine-readable code:

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 5 credit(s); your balance is 3.",
    "credits_required": 5,
    "credits_remaining": 3
  }
}

Status	Code	Meaning
400	`invalid_request`	A parameter is missing or invalid. The message says which.
401	`missing_api_key`, `invalid_api_key`	No key was sent, or it is wrong or revoked.
402	`insufficient_credits`	Your balance is lower than the request cost.
404	`unknown_endpoint`, `not_found`	There is no such endpoint, or the requested item (place, product, profile...) does not exist. Not charged.
429	`rate_limited`	Too many requests for your plan. Retry after `retry_after_ms` (also sent as a `Retry-After` header in seconds).
502	`upstream_error`	The search engine could not be reached or answered with an error. Not charged.
503	`service_unavailable`	The search service is temporarily down. Not charged.
504	`upstream_timeout`	The search engine did not answer in time. Not charged.

Rate limits

Limits apply per account (all of your API keys and the playground share one limit):

Plan	Rate limit
Free	1 request / 30 seconds
Lite	1 request / second
Starter	5 requests / second
Growth	10 requests / second

Deep requests (num=100, depth=100) fetch several results pages and can take a few seconds. Set your HTTP client timeout to at least 60 seconds.

Code examples

cURL

curl "https://serpfast.com/api/v1/search?q=best+running+shoes&gl=US&num=20" \
  -H "Authorization: Bearer $SERPFAST_KEY"

Node.js 18+

const params = new URLSearchParams({ q: "best running shoes", gl: "US", num: "20" });
const res = await fetch(`https://serpfast.com/api/v1/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPFAST_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
for (const r of data.organic_results) console.log(r.position, r.title, r.link);

Python

import os, requests

res = requests.get(
    "https://serpfast.com/api/v1/search",
    params={"q": "best running shoes", "gl": "US", "num": 20},
    headers={"Authorization": f"Bearer {os.environ['SERPFAST_KEY']}"},
    timeout=60,
)
res.raise_for_status()
for r in res.json()["organic_results"]:
    print(r["position"], r["title"], r["link"])

PHP

<?php
$query = http_build_query(["q" => "best running shoes", "gl" => "US", "num" => 20]);
$ch = curl_init("https://serpfast.com/api/v1/search?" . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SERPFAST_KEY")],
    CURLOPT_TIMEOUT => 60,
]);
$data = json_decode(curl_exec($ch), true);
foreach ($data["organic_results"] as $r) {
    echo $r["position"] . " " . $r["title"] . PHP_EOL;
}