Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "keyword": "albert einstein",
    "datetime_from": "2026-09-22 05:48:19",
    "datetime_to": "2026-10-02 05:48:19",
    "location_code": 2840,
    "language_code": "en",
    "limit": 10
  }
]'

curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "datetime_from": "2026-09-22 05:48:19",
    "datetime_to": "2026-10-02 05:48:19",
    "keyword": "albert einstein",
    "language_code": "en",
    "limit": 10,
    "location_code": 2840
  }
]
'

import requests

url = "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live"

payload = [
    {
        "datetime_from": "2026-09-22 05:48:19",
        "datetime_to": "2026-10-02 05:48:19",
        "keyword": "albert einstein",
        "language_code": "en",
        "limit": 10,
        "location_code": 2840
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      datetime_from: '2026-09-22 05:48:19',
      datetime_to: '2026-10-02 05:48:19',
      keyword: 'albert einstein',
      language_code: 'en',
      limit: 10,
      location_code: 2840
    }
  ])
};

fetch('https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'datetime_from' => '2026-09-22 05:48:19',
        'datetime_to' => '2026-10-02 05:48:19',
        'keyword' => 'albert einstein',
        'language_code' => 'en',
        'limit' => 10,
        'location_code' => 2840
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live"

	payload := strings.NewReader("[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "cost": 123,
  "status_code": 123,
  "status_message": "<string>",
  "tasks_count": 123,
  "tasks_error": 123,
  "time": "<string>",
  "version": "<string>",
  "tasks": [
    {
      "cost": 123,
      "data": {},
      "id": "<string>",
      "path": [
        "<string>"
      ],
      "result_count": 123,
      "status_code": 123,
      "status_message": "<string>",
      "time": "<string>",
      "result": [
        {
          "items": [
            {
              "check_url": "<string>",
              "datetime": "<string>",
              "item_types": [
                "<string>"
              ],
              "items": [
                {
                  "links": [
                    {
                      "description": "<string>",
                      "domain": "<string>",
                      "snippet": "<string>",
                      "title": "<string>",
                      "type": "<string>",
                      "url": "<string>",
                      "xpath": "<string>"
                    }
                  ],
                  "text": [
                    "<string>"
                  ],
                  "position": "<string>",
                  "rank_absolute": 123,
                  "rank_group": 123,
                  "se_type": "<string>",
                  "type": "<string>",
                  "xpath": "<string>"
                }
              ],
              "items_count": 123,
              "keyword": "<string>",
              "language_code": "<string>",
              "location_code": 123,
              "se_domain": "<string>",
              "se_results_count": 123,
              "se_type": "<string>",
              "spell": {
                "keyword": "<string>",
                "type": "<string>"
              },
              "type": "<string>"
            }
          ],
          "items_count": 123,
          "keyword": "<string>",
          "language_code": "<string>",
          "location_code": 123,
          "se_type": "<string>",
          "total_count": 123
        }
      ]
    }
  ]
}

DataForSEO

Historical SERPs

‌ This endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.  Usage-based billing; Default request estimate: $0.1356 USD (not a fixed price). Account-specific pricing and final settlement may differ.

POST

https://api.aisa.one

apis

dataforseo

dataforseo_labs

google

historical_serps

live

Reference example

# Fixed reference example. Playground inputs do not update this sample.
curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "keyword": "albert einstein",
    "datetime_from": "2026-09-22 05:48:19",
    "datetime_to": "2026-10-02 05:48:19",
    "location_code": 2840,
    "language_code": "en",
    "limit": 10
  }
]'

curl --request POST \
  --url https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "datetime_from": "2026-09-22 05:48:19",
    "datetime_to": "2026-10-02 05:48:19",
    "keyword": "albert einstein",
    "language_code": "en",
    "limit": 10,
    "location_code": 2840
  }
]
'

import requests

url = "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live"

payload = [
    {
        "datetime_from": "2026-09-22 05:48:19",
        "datetime_to": "2026-10-02 05:48:19",
        "keyword": "albert einstein",
        "language_code": "en",
        "limit": 10,
        "location_code": 2840
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      datetime_from: '2026-09-22 05:48:19',
      datetime_to: '2026-10-02 05:48:19',
      keyword: 'albert einstein',
      language_code: 'en',
      limit: 10,
      location_code: 2840
    }
  ])
};

fetch('https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'datetime_from' => '2026-09-22 05:48:19',
        'datetime_to' => '2026-10-02 05:48:19',
        'keyword' => 'albert einstein',
        'language_code' => 'en',
        'limit' => 10,
        'location_code' => 2840
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live"

	payload := strings.NewReader("[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"datetime_from\": \"2026-09-22 05:48:19\",\n    \"datetime_to\": \"2026-10-02 05:48:19\",\n    \"keyword\": \"albert einstein\",\n    \"language_code\": \"en\",\n    \"limit\": 10,\n    \"location_code\": 2840\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "cost": 123,
  "status_code": 123,
  "status_message": "<string>",
  "tasks_count": 123,
  "tasks_error": 123,
  "time": "<string>",
  "version": "<string>",
  "tasks": [
    {
      "cost": 123,
      "data": {},
      "id": "<string>",
      "path": [
        "<string>"
      ],
      "result_count": 123,
      "status_code": 123,
      "status_message": "<string>",
      "time": "<string>",
      "result": [
        {
          "items": [
            {
              "check_url": "<string>",
              "datetime": "<string>",
              "item_types": [
                "<string>"
              ],
              "items": [
                {
                  "links": [
                    {
                      "description": "<string>",
                      "domain": "<string>",
                      "snippet": "<string>",
                      "title": "<string>",
                      "type": "<string>",
                      "url": "<string>",
                      "xpath": "<string>"
                    }
                  ],
                  "text": [
                    "<string>"
                  ],
                  "position": "<string>",
                  "rank_absolute": 123,
                  "rank_group": 123,
                  "se_type": "<string>",
                  "type": "<string>",
                  "xpath": "<string>"
                }
              ],
              "items_count": 123,
              "keyword": "<string>",
              "language_code": "<string>",
              "location_code": 123,
              "se_domain": "<string>",
              "se_results_count": 123,
              "se_type": "<string>",
              "spell": {
                "keyword": "<string>",
                "type": "<string>"
              },
              "type": "<string>"
            }
          ],
          "items_count": 123,
          "keyword": "<string>",
          "language_code": "<string>",
          "location_code": 123,
          "se_type": "<string>",
          "total_count": 123
        }
      ]
    }
  ]
}

Request contract

Method and path: POST /apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live
Runtime facts: 6ab8fec17df1d5dcdff2e036dd1eb40587752b774ec040ab4eb0cc6946c3dd3c

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "any_dataforseo_apis_v1_dataforseo_dataforseo_labs_e49bf5",
  "method": "POST",
  "path": "/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": [
            {
              "datetime_from": "2026-09-22 05:48:19",
              "datetime_to": "2026-10-02 05:48:19",
              "keyword": "albert einstein",
              "language_code": "en",
              "limit": 10,
              "location_code": 2840
            }
          ],
          "items": {
            "oneOf": [
              {
                "example": [
                  {
                    "datetime_from": "2026-09-22 05:48:19",
                    "datetime_to": "2026-10-02 05:48:19",
                    "keyword": "albert einstein",
                    "language_code": "en",
                    "limit": 10,
                    "location_code": 2840
                  }
                ],
                "properties": {
                  "date_from": {
                    "description": "<em>starting date of the time range</em><br>optional field<br>if you don't specify this field, the API will return all SERPs collected for 365 days starting from the current <code>datetime</code> value;<br>minimal possible value: 365 days from the current <code>datetime</code> value;<br>date format: <code>\"yyyy-mm-dd\"</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "date_to": {
                    "description": "<em>ending date of the time range</em><br>optional field<br>if you don't specify this field, the today's date will be used by default;<br>date format: <code>\"yyyy-mm-dd\"</code>;<br>example:<br><code>\"2021-09-01\"</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "keyword": {
                    "description": "<em>keyword</em><br><strong>required field</strong><br>you can specify <strong>up to 700 characters</strong> in the <code>keyword</code> field;<br>all %## will be decoded (plus character ‘+’ will be decoded to a space character);<br>if you need to use the “%” character for your <code>keyword</code>, please specify it as “%25”;<br>if you need to use the “+” character for your <code>keyword</code>, please specify it as “%2B”",
                    "type": "string"
                  },
                  "language_code": {
                    "description": "<em>unique language identifier</em><br><strong>required field if you don't specify</strong> <code>language_name</code><br><strong>Note:</strong> it is required to specify either <code>language_name</code> or <code>language_code</code><br>you can receive the list of available languages with their <code>language_code</code> parameters by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>example:<br><code class=\"long-string\">en</code>",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "language_name": {
                    "description": "<em>full name of the language</em><br><strong>required field if you don't specify</strong> <code>language_code</code><br><strong>Note:</strong> it is required to specify either <code>language_name</code> or <code>language_code</code><br>you can receive the list of available languages with their <code>language_name</code> parameters by making a separate request to the <br><code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>example:<br><code class=\"long-string\">English</code>",
                    "type": "string"
                  },
                  "location_code": {
                    "description": "<em>unique location identifier</em><br><strong>required field if you don't specify</strong> <code>location_name</code><br><strong>Note:</strong> it is required to specify either <code>location_name</code> or <code>location_code</code><br>you can receive the list of available locations with their <code>location_code</code> by making a separate request to <code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>example:<br><code class=\"long-string\">2840</code>",
                    "type": "integer"
                  },
                  "location_name": {
                    "description": "<em>full name of the location</em><br><strong>required field if you don't specify</strong> <code>location_code</code><br><strong>Note:</strong> it is required to specify either <code>location_name</code> or <code>location_code</code><br>you can receive the list of available locations with their <code>location_name</code> by making a separate request to <code>https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages</code><br>example:<br><code class=\"long-string\">United Kingdom</code>",
                    "type": "string"
                  },
                  "tag": {
                    "description": "<em>user-defined task identifier</em><br>optional field<br><em>the character limit is 255</em><br>you can use this parameter to identify the task and match it with the result<br>you will find the specified <code>tag</code> value in the <code>data</code> object of the response",
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            ],
            "type": [
              "object",
              "null"
            ]
          },
          "type": "array"
        }
      }
    }
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "cost_contract": "response_usd",
    "customer_multiplier": 1.0,
    "customer_pricing": "provider_cost_multiplier",
    "default_request_estimate_usd": 0.1356,
    "estimate_source": "profile_seed",
    "evidence_source": "response_body"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

Usage-based billing; Default request estimate: $0.1356 USD (not a fixed price). Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Default request reference estimate (USD): 0.1356
Cost contract: response_usd
Published reference multiplier: 1.0
Settlement evidence source: response_body

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

date_from

string | null

starting date of the time range
optional field
if you don't specify this field, the API will return all SERPs collected for 365 days starting from the current datetime value;
minimal possible value: 365 days from the current datetime value;
date format: "yyyy-mm-dd"

date_to

string | null

ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: "yyyy-mm-dd";
example:
"2021-09-01"

keyword

string

keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”

language_code

string | null

unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
en

language_name

string

full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name parameters by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
English

location_code

integer

unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
2840

location_name

string

full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:
United Kingdom

tag

string | null

user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response

Example:

[
  {
    "datetime_from": "2026-09-22 05:48:19",
    "datetime_to": "2026-10-02 05:48:19",
    "keyword": "albert einstein",
    "language_code": "en",
    "limit": 10,
    "location_code": 2840
  }
]

Response

object | null

Successful operation

cost

number<double> | null

total tasks cost, USD

status_code

integer | null

general status code you can find the full list of the response codes here

status_message

string | null

general informational message you can find the full list of general informational messages here

tasks_count

integer<int64> | null

the number of tasks in the tasks array

tasks_error

integer<int64> | null

the number of tasks in the tasks array returned with an error

time

string | null

total execution time, seconds

version

string | null

the current version of the API

tasks

(object | null)[] | null

array of tasks

Show child attributes

Overview

Models

Search & Research

Finance & Crypto

Social & Media

SEO & Web Intel

Sales & Email

Travel & Other

Historical SERPs

Request contract

Cost and request rules

Authorizations

Body

Response

​Request contract

​Cost and request rules

Authorizations

Body

Response

Request contract

Cost and request rules