Research Seo Keywords

POST

/seo/keywords/research

• Production
• QA

SPENDS CREDITS. Keyword ideas around a seed, from the paid data provider.

mode picks the provider report: ideas, related, suggestions, or auto to let the app choose. Rows come back in that report’s own shape.

Runs the app’s per-organisation provider rate limit (429 past it) and its fail-closed credit check (402 when the balance is exhausted) before anything is fetched. A provider outage is a 502 that says so.

Authorizations

• BearerAuth

Parameters

Header Parameters

X-Target-Org-Id

Any of:

string

string

null

null

Request Body ^required

Mirrors ResearchKeywordsRequest.

limit is capped at 150 - the same ceiling the app, the agent tool and the UI share - so a larger ask is a 422 here rather than a silent truncation. Send seed_keyword OR seed_domain (a whole site), never both. The market defaults to the organisation’s keyword market; domain is its own site, used for your_rank. The same research within 24 hours is free and says cached_at.

object

device

Any of:

string

string

Allowed values: desktop mobile

null

null

domain

Any of:

string

string

<= 255 characters

null

null

language_code

Any of:

string

string

<= 10 characters

null

null

limit

integer

default: 150 >= 1 <= 150

location_code

Any of:

integer

integer

null

null

mode

string

default: auto

Allowed values: auto ideas related suggestions

seed_domain

Any of:

string

string

>= 3 characters <= 255 characters

null

null

seed_keyword

Any of:

string

string

>= 1 characters <= 500 characters

null

null

Responses

200

Successful Response

object

data

required

Mirrors ResearchKeywordsResponse.

keywords rows are the provider’s row shape for the chosen mode, passed through rather than flattened, because the four modes return different columns and flattening would drop the ones a caller asked for.

object

cached_at

Any of:

string

string

null

null

keywords

Array<object>

default:

object

key

additional properties

any

locale

Any of:

SeoResearchLocale

Mirrors ResearchLocaleDTO.

object

device

required

string

Allowed values: desktop mobile

language_code

required

string

location_code

required

integer

null

null

seed

Any of:

SeoKeywordRow

Mirrors KeywordRow.

object

ai_overview_present

boolean

companies_researching

Any of:

integer

integer

null

null

competition

number

cpc

Any of:

number

number

null

null

cpc_high

Any of:

number

number

null

null

cpc_low

Any of:

number

number

null

null

est_clicks

Any of:

integer

integer

null

null

intent

Any of:

string

string

null

null

intents

Array<string>

default:

keyword

required

string

keyword_difficulty

Any of:

integer

integer

null

null

parent_topic

Any of:

string

string

null

null

parent_topic_volume

Any of:

integer

integer

null

null

results_count

Any of:

integer

integer

null

null

search_volume

integer

search_volume_avg

Any of:

integer

integer

null

null

serp_features

Array<string>

default:

trend

Array<integer>

default:

trend_12m

Array<integer>

default:

volume_spike

boolean

your_rank

Any of:

integer

integer

null

null

zero_click_share

Any of:

number

number

null

null

zero_click_source

Any of:

string

string

Allowed values: clickstream estimate

null

null

null

null

seed_domain

Any of:

string

string

null

null

pagination

Any of:

PaginationMeta

object

has_next

required

Whether there are more pages

boolean

limit

required

Items per page

integer

next_cursor

Any of:

string

string

null

null

notes

Any of:

Array<string>

Array<string>

null

null

page

required

Current page number (1-indexed)

integer

total

required

Total number of items

integer

total_available

Any of:

integer

integer

null

null

total_is_lower_bound

Any of:

boolean

boolean

null

null

null

null

422

Validation Error

object

detail

Array<object>

object

loc

required

Array

msg

required

string

type

required

string