v0.2.0-beta

OpenAPI 3.1.0

Setting Google Ads Advertisers SERP Tasks

Felo API Support

MIT

Server

https://openapi.felo.ai

Client Libraries

Shell Curl

DataForSEO

SEO, search-engine results, keyword research, backlinks and AI visibility data.

DataForSEO Operations

post/v1/beta/dataforseo/serp/google/ads_advertisers/task_post

Setting Google Ads Advertisers SERP Tasks

Queues the advertisers matching a query in Google's ads transparency data on Google, returning a task id in tasks[0].id. Wrapped in DataForSEO's envelope: data in tasks[0].result, outcome in tasks[0].status_code - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.

Pricing reference

Metering: Reported response cost.
Reference request estimate: USD 0.02.
Reference customer multiplier: 1.0. Do not apply it again to a settled customer amount.

Reference metadata only, not an account quote, a guaranteed price or a spending cap. Resource credits are not Felo credits. Final charges follow Felo billing records.

Body

application/json

Type: array (object | null)[]
- keyword
  Type: 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”
  
  learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article
- location_code
  Type: integer | null
  
  search engine location code
  
  optional field
  
  if you use this field, you don't need to specify location_name or location_coordinate
  
  you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locations
  
  example:
  
  2840
  
  Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
- location_coordinate
  Type: string | null
  
  GPS coordinates of a location
  
  optional field
  
  if you use this field, you don't need to specify location_name or location_code
  
  example:
  
  52.6178549,-155.352142
  
  Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
- location_name
  Type: string | null
  
  full name of search engine location
  
  optional field
  
  if you use this field, you don't need to specify location_code or location_coordinate
  
  you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locations
  
  example:
  
  London,England,United Kingdom
  
  Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations
- pingback_url
  Type: string | null
  
  notification URL of a completed task
  
  optional field
  
  when a task is completed we will notify you by GET request sent to the URL you have specified
  
  you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
  
  example:
  
  http://your-server.com/pingscript?id=$id
  
  http://your-server.com/pingscript?id=$id&tag=$tag
  
  Note: special characters in pingback_url will be urlencoded;
  
  i.a., the # character will be encoded into %23
  
  learn more on our Help Center
- postback_data
  Type: string
  
  postback_url datatype
  
  required field if you specify postback_url
  
  corresponds to the function you used for setting a task
  
  possible values:
  
  advanced
- postback_url
  Type: string | null
  
  URL for sending task results
  
  optional field
  
  once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
  
  you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
  
  example:
  
  http://your-server.com/postbackscript?id=$id
  
  http://your-server.com/postbackscript?id=$id&tag=$tag
  
  Note: special characters in postback_url will be urlencoded;
  
  i.a., the # character will be encoded into %23
  
  learn more on our Help Center
- priority
  Type: integer | null
  
  task priority
  
  optional field
  
  can 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 Pricing page.
- tag
  Type: 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

Responses

200
Type: object | null · Response36Afe1097B20_SerpGoogleAdsAdvertisersTaskPostResponseInfo
cost
Type: number | null Format: double

total tasks cost, USD

status_code
Type: integer | null

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

status_message
Type: string | null

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

tasks
Type: array (object | null)[] | null

array of tasks

Type: object | null · Response36Afe1097B20_SerpGoogleAdsAdvertisersTaskPostTaskInfo
cost
Type: number | null Format: double

total tasks cost, USD

data
Type: object | null

contains the same parameters that you specified in the POST request

propertyName
Type: object | null
id
Type: string | null

task identifier unique task identifier in our system in the UUID format

path
Type: array (string | null)[] | null

URL path

result
Type: object | null

array of results
in this case, the value will be null

result_count
Type: integer | null Format: int64

number of elements in the result array

status_code
Type: integer | null

status code of the task generated by DataForSEO, can be within the following range: 10000-60000 you can find the full list of the response codes here

status_message
Type: string | null

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

time
Type: string | null

execution time, seconds

tasks_count
Type: integer | null Format: int64

the number of tasks in the tasks array

tasks_error
Type: integer | null Format: int64

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

time
Type: string | null

total execution time, seconds

version
Type: string | null

the current version of the API
application/json
400

The request could not be processed. Check the request parameters.
401

A valid Felo API key is required.
402

The request cannot proceed because a billing requirement is not met.
403

The account is not permitted to perform this operation.
429

A request or spending limit has been reached.
502

The service could not complete the request.
503

The API or billing service is temporarily unavailable.
504

The service timed out while processing the request.
default

Error response; upstream passthrough responses may use provider formats

application/json

post/v1/beta/dataforseo/serp/google/ads_advertisers/task_post

curl https://openapi.felo.ai/v1/beta/dataforseo/serp/google/ads_advertisers/task_post \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "location_code": 2840,
    "keyword": "apple"
  }
]'

Show Schema

{
  "version": null,
  "status_code": null,
  "status_message": null,
  "time": null,
  "cost": null,
  "tasks_count": null,
  "tasks_error": null,
  "tasks": [
    {
      "id": null,
      "status_code": null,
      "status_message": null,
      "time": null,
      "cost": null,
      "result_count": null,
      "path": [
        null
      ],
      "data": null,
      "result": null
    }
  ]
}

Successful operation

Need help?

Contact Support for API, billing, and account questions.
Chat with Felo developers on Discord.
Check out our changelog.
Need volume pricing or procurement help? Contact Sales.
Building with an LLM? Read llms.txt.

Setting Google Ads Advertisers SERP Tasks

AuthenticationRequired

DataForSEO

Setting Google Ads Advertisers SERP Tasks

Pricing reference

Need help?