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

Serp

Changed on Jul 31, 2026

Google Ads Search provides information on ads that are run by advertisers on Google Ads. Information is based on the Ads Transparency platform and adapted for the convenience of DataForSEO users. ‌‌

post/v3/serp/google/ads_search/task_post

Request

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

Request body

advertiser_idsstring[]

advertiser identifiersrequired field if <code>target</code> is not specified you can specify the maximum of 25 values in this array;<code>advertiser_ids</code> values for this parameter can be found in the <a href="http://docs.dataforseo.com/v3/serp/google/ads_advertisers/task_get/advanced/" rel="noopener noreferrer" target="_blank">Google Ads Advertisers</a> endpoint;

targetstring

domain namerequired field if <code>advertiser_ids</code> is not specifieddomain name associated with an advertiser account

location_codeinteger nullable

search engine location codeoptional fieldif 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/ads_search/locations</code>example:<code class="long-string">2840</code> Note: if you don't specify <code>location_name</code>, <code>location_code</code>, or <code>location_coordinate</code>, the ads will be searched across all the available locations

depthinteger nullable

parsing depthoptional fieldnumber of results in SERPdefault value: <code>40</code>max value: <code>700</code> Your account will be billed per each SERP containing up to 40 results;Setting depth above 40 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 40 results</a>;The cost can be calculated on the <a title="Pricing" href="https://dataforseo.com/pricing/serp/google-ads-search-serp-api" target="_blank" rel="noopener noreferrer">Pricing</a> page.

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-ads-search-serp-api" target="_blank" rel="noopener noreferrer">Pricing</a> page.

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>

location_namestring nullable

full name of search engine locationoptional fieldif 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/ads_search/locations</code>example:<code class="long-string">London,England,United Kingdom</code> Note: if you don't specify <code>location_name</code>, <code>location_code</code>, or <code>location_coordinate</code>, the ads will be searched across all the available locations

location_coordinatestring nullable

GPS coordinates of a locationoptional fieldif you use this field, you don't need to specify <code>location_name</code> or <code>location_code</code>example:<code class="long-string">52.6178549,-155.352142</code> Note: if you don't specify <code>location_name</code>, <code>location_code</code>, or <code>location_coordinate</code>, the ads will be searched across all the available locations

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

platformstring nullable

advertising platformoptional fieldpossible values: <code>all</code>, <code>google_play</code>, <code>google_maps</code>, <code>google_search</code>, <code>google_shopping</code>, <code>youtube</code>default value: <code>all</code>

formatstring nullable

ad formatoptional fieldpossible values: <code>all</code>, <code>text</code>, <code>image</code>, <code>video</code>

date_fromstring

starting date of the time rangeoptional fieldrequired field if <code>date_to</code> is specified; date format: <code>"yyyy-mm-dd"</code>minimum value: 2018-05-31maximum value: today's dateexample:<code>"2020-01-01"</code>

date_tostring

ending date of the time rangeoptional fieldrequired field if <code>date_from</code> is specified; date format: <code>"yyyy-mm-dd"</code>minimum value: 2018-05-31maximum value: today's dateexample:<code>"2020-01-01"</code>

Example request

[
  {
    "location_code": 2840,
    "platform": "google_search",
    "advertiser_ids": [
      "AR13752565271262920705",
      "AR02439908557932462081"
    ]
  }
]

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 /////

Operation history (5 revisions)