Login Test it for free
Deutsch English Español Français Italiano Português 日本語
Test it for free Login
  • Getting started
  • Quick start
  • Information
  • Call limits
  • Google versions
  • List of versions
  • SERPS
  • Google Search queries
  • Google Maps queries
  • Query IDs
  • Retrieving SERPs
  • Callback URL
  • SERPs processing status
  • Request history
  • Billing
  • Remaining credit
  • Payment methods

Semscraper API documentation

Quick start

Three steps to get your first Google SERP as JSON.

  1. Create your account: 1,000 SERPs are free, no credit card required. Then copy your key from the API keys menu of your account. Send it in the Authorization: Bearer header of every call. Create a free account
  2. Send your keywords with POST /v1/serp, up to 1,000 per call. The response returns the ID and the cost of each SERP: this is the only time you are billed.
    Send a keyword
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "pancake recipe", "device": "desktop", "location": "us", "language": "en", "depth": 1}]'
  3. Retrieve the result with GET /v1/serp and the ID you received: replace SERP_ID with the value of the data[0].id field returned in the previous step.Collection is asynchronous: while the status is pending or processing, try again a little later. Retrieval is never billed.
    Retrieve the SERP
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

To be notified without polling the API, add a callback_url to your requests. For hundreds of thousands of keywords, see the Bulk SERP API.

Information

Call limits

Limit the number of API calls
GET : 500 calls per minute
POST : 500 calls per minute

Google versions

List of versions

Get the location and language parameters required to retrieve Google SERPs.
get
https://api.semscraper.com/v1/serp/google/location
Authorizations : Bearer {api_key}
  • Request
  • Successful response
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "us",
            "language": "en",
            "host": "google.com",
            "name": "United States"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERPs

Google Search queries

Creating Google Search SERPs queries
The data must be sent in a JSON array. Each element must contain the following fields.
Limit
The JSON array can contain 1000 elements, so you can create 1000 SERPs scrapes in a single call.
post
https://api.semscraper.com/v1/serp
Authorizations : Bearer {api_key}
Parameters
search_engine
Required
string
Choice of search engine :
Google Search (value: google_search)
keyword
Required
string
Keywords to search on the search engine
device
Required
string
Device:
Computer (value: desktop)
Mobile (value: mobile)
depth
Required
integer
Page depth, we retrieve Google SERPs with pagination. This parameter must be between 1 (about 10 results) and 10 (about 100 results).
location
Required
string
Search engine location code
language
Required
string
Search engine language
geolocation
string
Geolocates a Google SERP. Give the city, region and country separated by commas (e.g. Nice, Alpes-Maritimes, France), or a GPS position as latitude,longitude in decimal degrees (e.g. 43.7102,7.2620).
priority
integer
Allows you to prioritize your requests, which are processed in descending order of priority. Value between 1 (low) and 10 (high).
callback_url
string
Allows you to specify a URL to which we will send you the results of the keyword once it has been processed.
Result block types
Possible values of the type field. A block is only present in the response when Google displays it for the requested keyword.
Results and ads
organic
Organic result
Standard organic search result.
sitelinks
Sitelinks
Secondary link attached to an organic result.
paid_top
Top ad
Paid ad above the organic results.
paid_bottom
Bottom ad
Paid ad below the organic results.
Rich blocks
featured_snippet
Featured snippet
Highlighted snippet above the organic results.
knowledge_graph
Knowledge panel
Item from the panel shown on the right of the SERP.
images
Images
Thumbnail from the images block.
videos
Videos
Video from the videos block.
top_stories
Top stories
Article from the top stories block.
shopping
Shopping
Product from the Google Shopping carousel.
recipes
Recipes
Recipe from the recipes block.
local_pack
Local pack
Business from the local pack, sourced from Google Maps.
visual_digest
Visual digest
Item from the visual digest generated by Google.
Suggestions and follow-ups
people_also_ask
People also ask
Question from the People also ask block.
related_searches
Related searches
Related search suggested at the bottom of the page.
find_results_on
Find results on
Link from the Find results on block.
location_sites
Location sites
Site listed in a location-related block.
AI Overview
ai_overview_citation
Citation
Brand cited in the AI-generated text.
ai_overview_citation_source
Citation source
Source of a citation, shown on hover over it.
ai_overview_panel
Source panel
Site listed in the side panel of sources.
  • Request
  • Successful response
  • Error response
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Google Maps queries

Creating Google Maps SERPs queries
The data must be sent in a JSON array. Each element must contain the following fields.
Limit
The JSON array can contain 1000 elements, so you can create 1000 SERPs scrapes in a single call.
post
https://api.semscraper.com/v1/serp
Authorizations : Bearer {api_key}
Parameters
search_engine
Required
string
Choice of search engine :
Google Maps (value: google_maps)
keyword
Required
string
Keywords to search on the search engine
depth
Required
integer
Page depth, we retrieve Google SERPs with pagination. This parameter must be between 1 (about 10 results) and 10 (about 100 results).
location
Required
string
Search engine location code
language
Required
string
Search engine language
geolocation
string
Geolocates a Google SERP. Give the city, region and country separated by commas (e.g. Nice, Alpes-Maritimes, France), or a GPS position as latitude,longitude in decimal degrees (e.g. 43.7102,7.2620). With a GPS position, you can add an optional zoom level (e.g. 43.7102,7.2620,16z).
priority
integer
Allows you to prioritize your requests, which are processed in descending order of priority. Value between 1 (low) and 10 (high).
callback_url
string
Allows you to specify a URL to which we will send you the results of the keyword once it has been processed.
  • Request
  • Successful response
  • Error response
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Query IDs

List of IDs for completed SERPs that you have not yet retrieved.
This method allows you to obtain the IDs of all SERPs already processed but never retrieved. You can then call the SERP retrieval endpoint using these IDs.
get
https://api.semscraper.com/v1/serp
Authorizations : Bearer {api_key}
  • Request
  • Successful response
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 2,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}

Retrieving SERPs

Retrieve Google SERPs by ID
Retrieve multiple SERPs in one call (in JSON or HTML format) by providing multiple IDs separated by a comma.
Limit
You can specify up to 100 IDs, allowing you to retrieve 100 SERPs in a single call.
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
Authorizations : Bearer {api_key}
Parameters
ids
Required
string
Comma-separated list of IDs.
output
Required
string
Choice of output format :
JSON (value: json)
HTML (value: html)
Result Format
  • Google Search
  • Google Maps
type
string
Result block type (organic, videos, images, people_also_ask, local_pack...)
rank_type
integer
Position of the element within its own block type (e.g., 3rd organic result = 3)
rank_serp
integer
Absolute position in the entire SERP, across all blocks, based on the actual vertical position on the page (in pixels)
page
integer
Page number of the SERP where the item appears
pixel
integer
Vertical position of the element on the page, in pixels from the top
domain
string
URL domain
url
string
Result URL
title
string
Displayed result title
description
string
Description / Displayed excerpt from the results
brand
string
Cited brand, or the source label as displayed by Google. Only on ai_overview_citation, ai_overview_citation_source and ai_overview_panel blocks. On a citation the URL is often empty, making the brand the only information carried by the item.
visible
boolean
Whether the item is shown straight away in the AI Overview (true) or only after expanding it (false). Only on AI Overview blocks. Always false for ai_overview_citation_source, which appears on hover over a citation.
rating
float
Average rating displayed by Google (e.g. 4.1). Only on organic and local_pack blocks, null when the result shows no stars.
reviews
integer
Number of reviews behind the rating. Only on organic and local_pack blocks, null when the result shows no stars.
price_range
string
Price range of the business as displayed by Google (e.g. \"20–30 €\"). Only on local_pack blocks, null when absent.
details
array
Information displayed under the business, in Google's order and language: price, category, address, opening hours, services… Only on local_pack blocks. Neither the order nor the presence of each piece of information is guaranteed.
serp_info.ai_overview
object
AI Overview of the SERP, in the serp_info object (not in results). Holds type, text and complete.
serp_info.ai_overview.type
string
How the AI Overview is displayed: sync (in the page as soon as it loads), async (generated by Google on the fly, after the page has loaded) or none (no AI Overview).
serp_info.ai_overview.text
string
AI-generated text, as plain text (no formatting or links). null when the SERP has no AI Overview or the text could not be read.
serp_info.ai_overview.complete
boolean
True when the AI Overview had finished generating at capture time. false when the text is missing or may be incomplete.
rank_type
integer
Position of the element within its own block type (e.g., 3rd organic result = 3)
rank_serp
integer
Absolute position in the entire SERP, across all blocks, based on the actual vertical position on the page (in pixels)
page
integer
Page number of the SERP where the item appears
pixel
integer
Vertical position of the element on the page, in pixels from the top
title
string
Displayed result title
cid
string
Google ID (CID) of the business listing
reviews
integer
Number of reviews
rating
float
Average rating out of 5
website
string
Business website
type
string
Establishment category (e.g., Restaurant)
address
string
Address
status_label
string
Opening Status (e.g., Open, Closed)
status_detail
string
Status details (e.g., hours)
comment
string
Displayed review / excerpt
images
array
List of images in this entry
  • Request
  • Successful response
  • Error response
Status: 200 OK
{
    "status": "success",
    "request_ms": 41,
    "count": 1,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": "",
            "cost": 0.0003,
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "serp_info": {
                "result_count": 1500000000,
                "ai_overview": {
                    "type": "async",
                    "text": "A keyword is a word or phrase that users type into a search engine to find information...",
                    "complete": true
                }
            },
            "results": [
                {
                    "type": "people_also_ask",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 4,
                            "page": 1,
                            "pixel": 806,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
                            "title": "What is a keyword example?",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 5,
                            "page": 1,
                            "pixel": 858,
                            "domain": "toolsqa.com",
                            "url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
                            "title": "What is the example keyword used for?",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 6,
                            "page": 1,
                            "pixel": 911,
                            "domain": "www.editage.com",
                            "url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
                            "title": "How do you write keywords examples?",
                            "description": ""
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 7,
                            "page": 1,
                            "pixel": 964,
                            "domain": "libguides.lvc.edu",
                            "url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
                            "title": "What is an example of a keyword search?",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "videos",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 1,
                            "page": 1,
                            "pixel": 223,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
                            "title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 2,
                            "page": 1,
                            "pixel": 374,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
                            "title": "What Are Keywords? Everything You Need To Know (and more)",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 3,
                            "page": 1,
                            "pixel": 526,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
                            "title": "Keyword Research Tutorial: From Start to Finish",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "organic",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 8,
                            "page": 1,
                            "pixel": 1077,
                            "domain": "www.seoquantum.com",
                            "url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
                            "title": "The 6 Types of Keywords in Organic SEO",
                            "description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 9,
                            "page": 1,
                            "pixel": 1223,
                            "domain": "storychief.io",
                            "url": "https://storychief.io/blog/seo-keyword-research-examples",
                            "title": "10 Clever SEO Keyword Research Examples",
                            "description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 10,
                            "page": 1,
                            "pixel": 1369,
                            "domain": "www.indeed.com",
                            "url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
                            "title": "19 Types of Keywords",
                            "description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 11,
                            "page": 1,
                            "pixel": 1515,
                            "domain": "www.usg.edu",
                            "url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
                            "title": "Keyword Search",
                            "description": "In this case, the phrase alternative fuels and automobiles are the significant keywords.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 5,
                            "rank_serp": 12,
                            "page": 1,
                            "pixel": 1639,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g=1249281",
                            "title": "What are keywords and why are they important? - Guides",
                            "description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 6,
                            "rank_serp": 13,
                            "page": 1,
                            "pixel": 1785,
                            "domain": "www.tactee.fr",
                            "url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
                            "title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
                            "description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 7,
                            "rank_serp": 14,
                            "page": 1,
                            "pixel": 1931,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/types-of-keywords",
                            "title": "10 Types of Keywords with Examples (+ How to Find Them)",
                            "description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 8,
                            "rank_serp": 15,
                            "page": 1,
                            "pixel": 2077,
                            "domain": "learn.microsoft.com",
                            "url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
                            "title": "C# Keywords and contextual keywords - C# reference",
                            "description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ...",
                            "rating": null,
                            "reviews": null
                        }
                    ]
                },
                {
                    "type": "local_pack",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 19,
                            "page": 1,
                            "pixel": 2520,
                            "domain": "lebistrotm.fr",
                            "url": "https://lebistrotm.fr/",
                            "title": "Le Bistrot M",
                            "description": "",
                            "rating": 4.6,
                            "reviews": 220,
                            "price_range": "20–30 €",
                            "details": [
                                "20–30 €",
                                "Restaurant",
                                "1 Pl. Xavier Taillade",
                                "Fermé",
                                "Ouvre à 18:30",
                                "Repas sur place",
                                "Aucun plat à emporter",
                                "Pas de livraison"
                            ]
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 20,
                            "page": 1,
                            "pixel": 2661,
                            "domain": "www.domainedesoliviers.fr",
                            "url": "http://www.domainedesoliviers.fr/",
                            "title": "Domaine des Oliviers",
                            "description": "",
                            "rating": 4.5,
                            "reviews": 1600,
                            "price_range": null,
                            "details": [
                                "Française",
                                "4 All. Paul Emile d'Allard",
                                "Fermé",
                                "Ouvre à 19:00",
                                "Hôtel discret avec piscine et restaurant"
                            ]
                        }
                    ]
                },
                {
                    "type": "images",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 16,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "searchfacts.com",
                            "url": "https://searchfacts.com/what-are-keywords-in-seo/",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 17,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/hub/seo/seo-keywords",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 18,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "ahrefs.com",
                            "url": "https://ahrefs.com/blog/what-are-keywords/",
                            "title": "",
                            "description": ""
                        }
                    ]
                }
            ]
        }
    ]
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Callback URL

Retrieving SERPs via a callback URL
You can receive the result of a SERP directly on a URL you provide us with when creating a query, simply by retrieving the HMAC key linked to the API key used.
  • Code
  • PHP
  • Python
  • Javascript
  • Ruby
  • Java
  • C#
  • GO
// 1) Read the raw body (JSON)
$raw = file_get_contents('php://input');

// 2) Retrieve the headers
$headers = function_exists('getallheaders') ? getallheaders() : [];
$signature = $headers['X-Signature'] ?? '';

// 3) (Optional) Verify the HMAC signature
$sharedSecret = 'HMAC_KEY';
$expected = hash_hmac('sha256', $raw, $sharedSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid signature';
    exit;
}

// 4) Decode the JSON
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid JSON';
    exit;
}

// 5) Process the data: a list holding the finished SERP
foreach ($data as $serp) {
    // $serp['id'], $serp['keyword'], $serp['results']...
}

// 6) Respond in JSON (optional, we log these responses for tracking purposes)
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'received_at' => gmdate('c'),
    'echo' => array_column($data, 'id')
]);

SERPs processing status

Current state of SERPs processing
Shows the number of SERPs according to their status:
Completed and results retrieved by user (status=done, fetched=true)
Completed and results not retrieved by user (status=done, fetched=false)
In process (status=processing)
Waiting (status=pending)
get
https://api.semscraper.com/v1/serp/status
Authorizations : Bearer {api_key}
  • Request
  • Successful response
Status: 200 OK
{
    "status": "success",
    "request_ms": 54,
    "count": 4,
    "data": [
        {
            "status": "done",
            "fetched": true,
            "count": 5
        },
        {
            "status": "done",
            "fetched": false,
            "count": 1000
        },
        {
            "status": "processing",
            "count": 0
        },
        {
            "status": "pending",
            "count": 0
        }
    ]
}

Request history

Lists your requests, newest first, with their configuration (keyword, search engine, device, location, language, depth…) and their status, without the SERP result.
Every request on the account is returned, whatever its status and whether it has already been fetched or not. This call does not mark them as fetched.

To paginate, call the endpoint again with the cursor parameter set to the next_cursor of the previous response, as long as has_more is true. The _links.next link holds the ready-to-use URL. To get the result of a request, use its _links.json or _links.html link.
Limit
10,000 requests per call
get
https://api.semscraper.com/v1/serp/list?date=2026-10-20&limit=1000
Authorizations : Bearer {api_key}
Parameters
date
string
Day the requests were created, in YYYY-MM-DD format (e.g. 2026-10-04). Without it, all dates are returned.
status
string
Filter on status: pending, processing or done. Without it, all statuses are returned.
limit
integer
Number of requests per page, from 1 to 10,000. Defaults to 1,000.
cursor
string
Pagination cursor: the next_cursor value from the previous response. Leave it out for the first page.
  • Request
  • Successful response
  • Error response
Status: 200 OK
{
    "status": "success",
    "request_ms": 38,
    "count": 2,
    "has_more": true,
    "next_cursor": "MTI4NDU2Nzg5",
    "data": [
        {
            "id": "SERP_ID",
            "search_engine": "google_search",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": null,
            "priority": 1,
            "callback_url": null,
            "status": "done",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:45",
            "updated_at": "2026-10-04 09:12:58",
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "search_engine": "google_maps",
            "keyword": "example keyword",
            "device": null,
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": "Nice, Alpes-Maritimes, France",
            "priority": 1,
            "callback_url": "https://example.com/callback",
            "status": "pending",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:44",
            "updated_at": null,
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ],
    "_links": {
        "next": {
            "href": "/v1/serp/list?date=2026-10-04&limit=1000&cursor=MTI4NDU2Nzg5",
            "method": "GET",
            "type": "application/json"
        }
    }
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "Invalid format for parameter: date",
    "code": 400
}

Billing

Remaining credit

Retrieves remaining credit
get
https://api.semscraper.com/v1/billing/credit
Authorizations : Bearer {api_key}
  • Request
  • Successful response
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

Payment methods

Available payment methods
get
https://api.semscraper.com/v1/billing/payment_methods
Authorizations : Bearer {api_key}
  • Request
  • Successful response
Status: 200 OK
{
    "status": "success",
    "request_ms": 43,
    "count": 3,
    "data": [
        {
            "id": 1,
            "name": "Perso",
            "num": "-4242",
            "expiration": "1226",
            "type": "Visa",
            "master": false
        },
        {
            "id": 30,
            "name": "Pro",
            "num": "-4444",
            "expiration": "1227",
            "type": "Mastercard",
            "master": true
        }
    ]
}