DataForSEO Labs Google Ranked Keywords
This endpoint will provide you with the list of keywords that any domain, subdomain, or webpage is ranking for. You will also get SERP elements related to the keyword position, as well as monthly searches and other data relevant to the returned keywords. The public input is a tasks array containing exactly one task per call. The task's optional filters field accepts official condition arrays, not a list of objects. A single condition can be ["ranked_serp_element.serp_item.rank_group","<=",10]. Multiple conditions can be combined as [["ranked_serp_element.serp_item.rank_group","<=",10],"and",["ranked_serp_element.serp_item.type","<>","paid"]], with nested "and"/"or" expressions supported. Matching keywords are not guaranteed; results depend on available data and the specified conditions. When using this tool, each order_by rule must be a fully qualified response field path, for example keyword_data.keyword_info.search_volume,desc or ranked_serp_element.serp_item.rank_group,asc; bare field names such as search_volume or rank_absolute are not accepted. You can set up to three sorting rules, separating the field path from asc/desc with a comma and using a separate array item for each additional rule. The default is ranked_serp_element.serp_item.rank_group ascending.
Pricing
| Condition | Charge |
|---|---|
| Without clickstream data (default) | 14.4 credits base fee + 0.2 credits per returned record |
| With clickstream data | 28.8 credits base fee + 0.3 credits per returned record |
Charges depend on clickstream inclusion and the number of results actually returned.
The starting price is the base query fee without clickstream data; returned records add the listed charges.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
tasks | array | Yes | No parameter description. | — |
tasks[].tag | string | null | No | No parameter description. | — |
tasks[].limit | integer | null | No | No parameter description. | — |
tasks[].offset | integer | null | No | No parameter description. | — |
tasks[].target | string | No | <em>domain name or page url</em><br><strong>required field</strong><br>the domain name of the target website, subdomain or URL of the target webpage;<br>the <strong>domain name</strong> must be specified <strong>without</strong> <code>https://</code> or <code>www.</code>;<br>the <strong>subdomain</strong> must be specified <strong>without</strong> <code>https://</code>;<br>the <strong>webpage URL</strong> must be specified <strong>with</strong> <code>https://</code> or <code>www.</code><br><strong>Note:</strong> if you specify the <strong>webpage URL</strong> without <code>https://</code> or <code>www.</code>, the result will be returned for the <strong>entire domain</strong> rather than the specific page | — |
tasks[].filters | array | null | No | No parameter description. | — |
tasks[].order_by | array | null | No | No parameter description. | — |
tasks[].item_types | array | null | No | No parameter description. | — |
tasks[].language_code | string | null | No | No parameter description. | — |
tasks[].language_name | string | null | No | No parameter description. | — |
tasks[].location_code | integer | null | No | No parameter description. | — |
tasks[].location_name | string | null | No | No parameter description. | — |
tasks[].ignore_synonyms | boolean | null | No | No parameter description. | — |
tasks[].load_rank_absolute | boolean | null | No | No parameter description. | — |
tasks[].historical_serp_mode | string | null | No | No parameter description. | — |
tasks[].include_clickstream_data | boolean | null | No | No parameter description. | — |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_dataforseo_labs_google_ranked_keywords' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"tasks": [
{
"filters": [
[
"ranked_serp_element.serp_item.rank_group",
"<=",
10
]
],
"item_types": [
"organic"
],
"language_code": "en",
"limit": 100,
"location_code": 2840,
"order_by": [
"keyword_data.keyword_info.search_volume,desc"
],
"tag": "competitor-dingli-cn-20261117",
"target": "cndingli.com"
}
]
}
}'{
"cost": 0.012,
"status_code": 20000,
"status_message": "Ok.",
"tasks": [
{
"cost": 0.012,
"data": {
"api": "dataforseo_labs",
"filters": [
[
"ranked_serp_element.serp_item.rank_group"
]
],
"function": "ranked_keywords",
"item_types": [
"organic"
],
"language_code": "en",
"limit": 100
},
"id": "11170139-2802-0381-0000-18724d2dbb11",
"path": [
"v3"
],
"result": [
{
"items": null,
"items_count": 0,
"language_code": "en",
"location_code": 2840,
"metrics": null,
"metrics_absolute": null
}
],
"result_count": 1
}
],
"tasks_count": 1,
"tasks_error": 0
}This example shows part of the response. Copied content is valid JSON.
Guides using this tool
See how this tool fits into real workflows

