Ranked Keywords

DataForSEO

Return keywords for which a domain ranks with positions, URLs and search metrics.

Capability: SEO keyword research
Current price: $0.0168/call
Availability: Ready to run

What this API does

Returns Google keywords for which a target domain, subdomain or URL ranks, including the matching SERP element and keyword metrics. Uses standard DataForSEO Labs data only; clickstream fields are deliberately excluded because they have a different supplier price. Billed as one live task plus each returned keyword.

Agents select this operation with tool ID dataforseo.ranked-keywords, then inspect its current executable contract before a run.

Public input and output shape

Input

historical_serp_modestring · optional

Value supplied for historical serp mode.

enum: live, lost, all

ignore_synonymsboolean · optional

Value supplied for ignore synonyms.

item_typesarray · optional

Value supplied for item types.

minItems: 1 · maxItems: 5

language_namestring · optional

Value supplied for language name.

minLength: 1 · maxLength: 100

limitinteger · optional

Value supplied for limit.

minimum: 1 · maximum: 1000

load_rank_absoluteboolean · optional

Value supplied for load rank absolute.

location_namestring · optional

Value supplied for location name.

minLength: 1 · maxLength: 200

offsetinteger · optional

Value supplied for offset.

minimum: 0 · maximum: 100000000

order_byarray · optional

Value supplied for order by.

maxItems: 3

targetstring · required

Value supplied for target.

minLength: 1 · maxLength: 2000

Output

itemsarray

Returned items value.

items_countnumber

Returned items count value.

targetstring

Returned target value.

total_countnumber

Returned total count value.

Example request and output

This reviewed worked example is shared with inspect. Inspect also returns the current executable schema and price estimate before a paid run.

Request

{
  "tool_id": "dataforseo.ranked-keywords",
  "input": {
    "limit": 1,
    "target": "dataforseo.com",
    "item_types": [
      "organic"
    ],
    "language_name": "English",
    "location_name": "United States"
  }
}

Output

{
  "items": [
    {
      "keyword_data": {
        "keyword": "dataforseo",
        "keyword_info": {
          "cpc": 1.5,
          "search_volume": 1000
        }
      },
      "ranked_serp_element": {
        "serp_item": {
          "url": "https://dataforseo.com/",
          "type": "organic",
          "rank_group": 1
        }
      }
    }
  ],
  "target": "dataforseo.com",
  "items_count": 1,
  "total_count": 1
}

Teaching errors and limitations

invalid_input: target is requiredexample: {"target":"dataforseo.com","location_name":"United States","language_name":"English","limit":1}
configuration_error: DataForSEO account access, funding, or cost controls blocked the request.Fund and verify the server-side DataForSEO account, then retry unchanged.

Use Ranked Keywords with Scrollport

Use Scrollport

Scrollport identifies and validates the best-in-class API tools and provides them on a pay-as-you-go basis so you don't need to maintain a separate provider account, subscription or credits.

Give your agent the setup prompt to receive $1 in trial credit and start using the tools right away.