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

Serp

Changed on Aug 11, 2026

‌‌ SERP API provides top 10 search engine results by default. These results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings.

post/v3/serp/google/organic/task_post

Request

Base URL: https://api.dataforseo.com
URL: https://api.dataforseo.com/v3/serp/google/organic/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”;if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘site:’, the charge per task will be multiplied by 5 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>example:<code class="long-string">2840</code>

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/languages</code>example:<code class="long-string">en</code>

depthinteger nullable

parsing depthoptional fieldnumber of results in SERPdefault value: <code>10</code>max value: <code>700</code> Your account will be billed per each SERP containing up to 10 results;Setting depth above 10 may result in additional charges <a href="https://dataforseo.com/help-center/how-many-results-scraped" rel="noopener noreferrer" target="_blank">if the search engine returns more than 10 results</a>;The cost can be calculated on the <a title="Pricing" href="https://dataforseo.com/pricing/serp/google-organic-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>

load_async_ai_overviewboolean nullable

load asynchronous ai overviewoptional fieldset to <code>true</code> to obtain <code>ai_overview</code> items is SERPs even if they are loaded asynchronously;if set to <code>false</code>, you will only obtain <code>ai_overview</code> items from cache;default value: <code>false</code>Note: you will be charged extra $0.0006 for using this parameter;if the element is absent or contains <code>"asynchronous_ai_overview": false</code>, all extra charges will be returned to your account balance

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 requestexample:<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 datatype that will be sent to your serverpossible values:<code>regular</code>, <code>advanced</code>, <code>html</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-organic-serp-api" target="_blank" rel="noopener noreferrer">Pricing</a> page.

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>example:<code class="long-string">London,England,United Kingdom</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,radius" formatthe maximum number of decimal digits for "latitude" and "longitude": 7the minimum value for "radius": 199 (mm)the maximum value for "radius": 199999 (mm)example:<code class="long-string">53.476225,-2.243572,200</code>

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/languages</code>example:<code class="long-string">English</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

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>

match_typestring

target match typerequired field if <code>stop_crawl_on_match</code> is specifiedtype of match for the <code>match_value</code>possible values:<code>domain</code> – specific domain or subdomain<code>with_subdomains</code> – main domain and subdomains<code>wildcard</code> – wildcard pattern

match_valuestring

target domain, subdomain, or wildcard valuerequired field if <code>stop_crawl_on_match</code> is specifiedspecify a target domain, subdomain, or wildcard value;Note: domain or subdomain must be specified without a request protocol;example: <code>"match_value": "dataforseo.com"</code>,<code>"match_value": "/blog/post-*"</code>

max_crawl_pagesinteger nullable

page crawl limitoptional fieldnumber of search results pages to crawlmax value: <code>100</code>Note: you will be charged for each page crawled (10 organic results per page);learn more about pricing on our <a href="https://dataforseo.com/pricing/serp/google-organic-serp-api" target="_blank">Pricing</a> page;Note#2: the <code>max_crawl_pages</code> and <code>depth</code> parameters complement each other;learn more at <a href="https://dataforseo.com/help-center/what-is-max-crawl-pages-and-how-does-it-work" rel="noopener noreferrer" target="_blank">our help center</a>

search_paramstring nullable

additional parameters of the search queryoptional field<a href="https://dataforseo.com/help-center/google-search-engine-parameters-and-how-to-use-them">get the list of available parameters and additional details here</a> Note: the following search engine parameters are not supported and will be automatically unset if specified: <code>lr</code>, <code>cr</code>, <code>as_qdr</code>, <code>as_sitesearch</code>, <code>as_occt</code>, <code>as_filetype</code>.

remove_from_urlstring[] nullable

remove specific parameters from URLsoptional fieldusing this field, you can specify up to 10 parameters to remove from URLs in the resultexample:<code>"remove_from_url": ["srsltid"]</code>

expand_ai_overviewboolean nullable

expand ai overviewoptional fieldset to <code>true</code> to expand the <code>ai_overview</code> item;default value: <code>false</code>;Note: this parameter applies only to <a href="/v3/serp/google/organic/task_get/html/?bash" rel="noopener noreferrer" target="_blank">HTML task results</a>

people_also_ask_click_depthinteger nullable

clicks on the corresponding elementoptional fieldspecify the click depth on the <code>people_also_ask</code> element to get additional <code>people_also_ask_element</code> items;Note your account will be billed $0.00015 extra for each click regardless of task priority;if the element is absent or we perform fewer clicks than you specified, all extra charges will be returned to your account balancepossible values: from <code>1</code> to <code>4</code>

group_organic_resultsboolean nullable

display related resultsoptional fieldif set to <code>true</code>, the <code>related_result</code> element in the response will be provided as a snippet of its parent organic result;if set to <code>false</code>, the <code>related_result</code> element will be provided as a separate organic result;default value: <code>true</code>

calculate_rectanglesboolean nullable

calcualte 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: you will be charged extra $0.0006 for using this parameter

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>

urlstring nullable

direct URL of the search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.example:<code class="long-string">https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS</code> Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: <code>lr</code>, <code>cr</code>, <code>as_qdr</code>, <code>as_sitesearch</code>, <code>as_occt</code>, <code>as_filetype</code>.

target_search_modestring nullable

target matching modeoptional fieldto enable this parameter, <code>stop_crawl_on_match</code> must also be enableddefines how the crawl should stop when multiple targets are specified in <code>stop_crawl_on_match</code>possible values: <code>all</code>, <code>any</code><code>all</code> – the crawl stops only when all specified targets are found<code>any</code> – the crawl stops when any single target is founddefault value: <code>any</code>learn more about this parameter on our <a href="https://dataforseo.com/help-center/how-to-use-new-crawl-control-parameters-in-google-organic-serp-api" target="_blank">Help Center</a>

find_targets_instring[] nullable

SERP element types to check for targetsoptional fieldto enable this parameter, <code>stop_crawl_on_match</code> must also be enabledspecifies which SERP element types should be checked for target matchesif not specified, all first-level elements with <code>url</code> and <code>domain</code> fields are checked for targetspossible values: <code>organic</code>, <code>paid</code>, <code>local_pack</code>, <code>featured_snippet</code>, <code>events</code>, <code>google_flights</code>, <code>images</code>, <code>jobs</code>, <code>knowledge_graph</code>, <code>local_service</code>, <code>map</code>, <code>scholarly_articles</code>, <code>third_party_reviews</code>, <code>twitter</code>Note: cannot contain the same element types as <code>ignore_targets_in</code>example:<code>"find_targets_in": ["organic", "featured_snippet"]</code>learn more about this parameter on our <a href="https://dataforseo.com/help-center/how-to-use-new-crawl-control-parameters-in-google-organic-serp-api" target="_blank">Help Center</a>

ignore_targets_instring[] nullable

SERP element types to exclude from target searchoptional fieldto enable this parameter, <code>stop_crawl_on_match</code> must also be enabledspecifies which SERP element types should be excluded when searching for target matchespossible values: <code>organic</code>, <code>paid</code>, <code>local_pack</code>, <code>featured_snippet</code>, <code>events</code>, <code>google_flights</code>, <code>images</code>, <code>jobs</code>, <code>knowledge_graph</code>, <code>local_service</code>, <code>map</code>, <code>scholarly_articles</code>, <code>third_party_reviews</code>, <code>twitter</code>Note: cannot contain the same element types as <code>find_targets_in</code>example:<code>"ignore_targets_in": ["paid", "images"]</code>learn more about this parameter on our <a href="https://dataforseo.com/help-center/how-to-use-new-crawl-control-parameters-in-google-organic-serp-api" target="_blank">Help Center</a>

se_domainstring nullable

search engine domainoptional fieldwe choose the relevant search engine domain automatically according to the location and language you specifyhowever, you can set a custom search engine domain in this fieldexample:<code>google.co.uk, google.com.au, google.de</code>, etc.

Example request

[
  {
    "language_code": "en",
    "location_code": 2840,
    "keyword": "albert einstein"
  },
  {
    "language_name": "English",
    "location_name": "United States",
    "keyword": "albert einstein",
    "priority": 2,
    "tag": "some_string_123",
    "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
  },
  {
    "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
    "postback_data": "html",
    "postback_url": "https://your-server.com/postbackscript"
  }
]

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

Aug 11, 2026ba59e41453da 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 /////
- 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 /////
- 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 (7 revisions)