POST /v3/serp/google/ai_mode/task_post – DataForSEO API documentation

Serp

Changed on Jul 31, 2026

‌ Google AI Mode SERP API provides search results from the AI Mode feature of Google Search.

post/v3/serp/google/ai_mode/task_post

Request

Base URL: https://api.dataforseo.com
URL: https://api.dataforseo.com/v3/serp/google/ai_mode/task_post
Auth: HTTP basic

Request body

keywordstring

keywordrequired fieldyou can specify up to 700 characters in the <code>keyword</code> fieldall %## will be decoded (plus character ‘+’ will be decoded to a space character)if you need to use the “%” character for your <code>keyword</code>, please specify it as “%25”;if you need to use the “+” character for your <code>keyword</code>, please specify it as “%2B” learn more about rules and limitations of <code>keyword</code> and <code>keywords</code> fields in DataForSEO APIs in this <a href="https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis" rel="noopener noreferrer" target="_blank">Help Center article</a>

location_codeinteger

search engine location coderequired field if you don't specify <code>location_name</code> or <code>location_coordinate</code>if you use this field, you don't need to specify <code>location_name</code> or <code>location_coordinate</code>you can receive the list of available locations of the search engines with their <code>location_code</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/google/locations</code>Note: check <a href="https://support.google.com/websearch/answer/16011537?hl=en&co=GENIE.Platform%3DAndroid#" target="_blank"> Google Search Help</a> for the list of countries where AI Mode is currently available

language_codestring

search engine language coderequired field if you don't specify <code>language_name</code>;if you use this field, you don't need to specify <code>language_name</code>;you can receive the list of available languages of the search engine with their <code>language_code</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/google/ai_mode/languages</code>

priorityinteger nullable

task priorityoptional fieldcan take the following values:1 – normal execution priority (set by default)2 – high execution priority You will be additionally charged for the tasks with high execution priority.The cost can be calculated on the <a title="Pricing" href="https://dataforseo.com/pricing/serp/google-ai-mode-serp-api" target="_blank" rel="noopener noreferrer">Pricing</a> page.

devicestring nullable

device typeoptional fieldreturn results for a specific device typecan take the values:<code>desktop</code>, <code>mobile</code>default value: <code>desktop</code>

pingback_urlstring nullable

notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the ‘$id’ string as a <code>$id</code> variable and ‘$tag’ as urlencoded <code>$tag</code> variable. We will set the necessary values before sending the request.example:<code>http://your-server.com/pingscript?id=$id</code><code>http://your-server.com/pingscript?id=$id&tag=$tag</code>Note: special characters in <code>pingback_url</code> will be urlencoded;i.a., the <code>#</code> character will be encoded into <code>%23</code> learn more on our <a href="https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api" target="_blank" rel="noopener noreferrer">Help Center</a>

postback_urlstring nullable

URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the <code>gzip</code> format to the <code>postback_url</code> you specifiedyou can use the ‘$id’ string as a <code>$id</code> variable and ‘$tag’ as urlencoded <code>$tag</code> variable. We will set the necessary values before sending the request.example:<code>http://your-server.com/postbackscript?id=$id</code><code>http://your-server.com/postbackscript?id=$id&tag=$tag</code>Note: special characters in <code>postback_url</code> will be urlencoded;i.a., the <code>#</code> character will be encoded into <code>%23</code> learn more on our <a href="https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api" target="_blank" rel="noopener noreferrer">Help Center</a>

postback_datastring

postback_url datatyperequired field if you specify <code>postback_url</code>corresponds to the function you used for setting a taskpossible values:<code>advanced</code>, <code>html</code>

location_namestring

full name of search engine locationrequired field if you don't specify <code>location_code</code> or <code>location_coordinate</code>if you use this field, you don't need to specify <code>location_code</code> or <code>location_coordinate</code>you can receive the list of available locations of the search engine with their <code>location_name</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/google/locations</code>Note: check <a href="https://support.google.com/websearch/answer/16011537?hl=en&co=GENIE.Platform%3DAndroid#" target="_blank"> Google Search Help</a> for the list of countries where AI Mode is currently available

language_namestring

full name of search engine languagerequired field if you don't specify <code>language_code</code>;if you use this field, you don't need to specify <code>language_code</code>;you can receive the list of available languages of the search engine with their <code>language_name</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/google/ai_mode/languages</code>;

osstring nullable

device operating systemoptional fieldif you specify <code>desktop</code> in the <code>device</code> field, choose from the following values: <code>windows</code>, <code>macos</code>default value: <code>windows</code>if you specify <code>mobile</code> in the <code>device</code> field, choose from the following values: <code>android</code>, <code>ios</code>default value: <code>android</code>

tagstring nullable

user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified <code>tag</code> value in the <code>data</code> object of the response

calculate_rectanglesboolean nullable

calculate pixel rankings for SERP elements in advanced resultsoptional fieldpixel ranking refers to the distance between the result snippet and top left corner of the screen;<a href="https://dataforseo.com/help-center/pixel-ranking-in-serp-api">Visit Help Center to learn more>></a>by default, the parameter is set to <code>false</code>Note: if set to <code>true</code>, the charge per task will be multiplied by 2

browser_screen_widthinteger nullable

browser screen widthoptional fieldyou can set a custom browser screen width to calculate pixel rankings for a particular device;can be specified within the following range: <code>240-9999</code>;by default, the parameter is set to:<code>1920</code> for <code>desktop</code>;<code>360</code> for <code>mobile</code> on <code>android</code>;<code>375</code> for <code>mobile</code> on <code>iOS</code>;Note: to use this parameter, set <code>calculate_rectangles</code> to <code>true</code>

browser_screen_heightinteger nullable

browser screen heightoptional fieldyou can set a custom browser screen height to calculate pixel rankings for a particular device;can be specified within the following range: <code>240-9999</code>;by default, the parameter is set to:<code>1080</code> for <code>desktop</code>;<code>640</code> for <code>mobile</code> on <code>android</code>;<code>812</code> for <code>mobile</code> on <code>iOS</code>;Note: to use this parameter, set <code>calculate_rectangles</code> to <code>true</code>

browser_screen_resolution_ratiointeger nullable

browser screen resolution ratiooptional fieldyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;can be specified within the following range: <code>0.5-3</code>;by default, the parameter is set to:<code>1</code> for <code>desktop</code>;<code>3</code> for <code>mobile</code> on <code>android</code>;<code>3</code> for <code>mobile</code> on <code>iOS</code>;Note: to use this parameter, set <code>calculate_rectangles</code> to <code>true</code>

location_coordinatestring

GPS coordinates of a locationrequired field if you don't specify <code>location_name</code> or <code>location_code</code>if you use this field, you don't need to specify <code>location_name</code> or <code>location_code</code><code>location_coordinate</code> parameter should be specified in the "latitude,longitude,zoom" formatif "zoom" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for "latitude" and "longitude": 7the minimum value for "zoom": 4zthe maximum value for "zoom": 18zexample:<code class="long-string">52.6178549,-155.352142,18z</code>

Example request

[
  {
    "language_code": "en",
    "location_code": 2840,
    "keyword": "what is google ai mode"
  }
]

Response

Successful operation

versionstring nullable

the current version of the API

status_codeinteger nullable

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

status_messagestring nullable

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

timestring nullable

total execution time, seconds

costnumber double nullable

total tasks cost, USD

tasks_countinteger nullable

the number of tasks in the tasks array

tasks_errorinteger nullable

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

Changes

Jul 31, 20268ef559e30ed4 Revision changes
- breaking
  the //////////// response's property type changed from string to object for status
Jul 26, 2026aa9f0f779507 Revision changes
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////

Operation history (6 revisions)