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.

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
}

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.

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

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.
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;
}