Account
whoami
account.whoami
Get the connected OpenSEO account, token scopes and remaining credits
Risk: read
await corsair.openseo.api.account.whoami({});
| Name | Type | Required | Description |
|---|---|---|---|
userEmail | string | null | No | — |
scopes | string[] | null | No | — |
mode | string | null | No | — |
creditsRemaining | number | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Ai Visibility
completeResearchSetup
aiVisibility.completeResearchSetup
Set up Prompt Research keywords for a project (can turn on weekly paid AI checks)
Risk: destructive
await corsair.openseo.api.aiVisibility.completeResearchSetup({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
keywords?: string[] | null,
status?: string | null,
review?: {
} | null | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
estimateCost
aiVisibility.estimateCost
Estimate the cost of AI visibility checks without running them
Risk: read
await corsair.openseo.api.aiVisibility.estimateCost({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', scheduleInterval: 'weekly' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
scheduleInterval | daily | weekly | monthly | No | Cadence for the monthly cost estimate. Defaults to the saved schedule, or weekly. |
patch | object | No | Optional proposed changes to estimate before saving. |
promptIds | string[] | No | — |
patch full type
patch full type
{
engines?: (chatgpt | gemini | google_ai_overview | google_ai_mode | claude | perplexity)[],
locationCode?: number,
languageCode?: string,
prompts?: {
id?: string,
text: string,
topic?: string,
paused?: boolean
}[],
archivePromptIds?: string[]
}
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
promptCount?: number | null,
engineCount?: number | null,
observations?: number | null,
providerCostUsd?: number | null,
costUsd?: number | null,
costCredits?: number | null,
runNowCostUsd?: number | null,
runNowCostCredits?: number | null,
scheduleInterval?: string | null,
checksPerMonth?: number | null,
monthlyCostUsd?: number | null,
currency: USD,
warnings?: string[] | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
explorePrompt
aiVisibility.explorePrompt
Ask a prompt in ChatGPT, Claude, Gemini or Perplexity and see answers, citations and brand mentions
Risk: destructive
await corsair.openseo.api.aiVisibility.explorePrompt({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
prompt: 'What is the best coffee subscription?',
models: ['chat_gpt'],
highlightBrand: 'Acme Coffee',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
prompt | string | Yes | The exact question to ask, up to 500 characters. Preserve the user’s wording. |
models | (chat_gpt | claude | gemini | perplexity)[] | No | Models to query: chat_gpt, claude, gemini, perplexity. Defaults to ChatGPT only. Supply a list to compare selected models; each uncached model uses credits. |
highlightBrand | string | No | Optional brand to highlight in answer text and citations. Does not change the prompt sent to the models. |
webSearch | boolean | No | Allow web search, default true. Answers report whether the model actually searched; permission does not guarantee citations. |
webSearchCountryCode | AD | AE | AF | AG | AI | AL | AM | AO | AQ | AR | AS | AT | AU | AW | AX | AZ | BA | BB | BD | BE | BF | BG | BH | BI | BJ | BL | BM | BN | BO | BQ | BR | BS | BT | BV | BW | BY | BZ | CA | CC | CD | CF | CG | CH | CI | CK | CL | CM | CN | CO | CR | CU | CV | CW | CX | CY | CZ | DE | DJ | DK | DM | DO | DZ | EC | EE | EG | EH | ER | ES | ET | FI | FJ | FK | FM | FO | FR | GA | GB | GD | GE | GF | GG | GH | GI | GL | GM | GN | GP | GQ | GR | GS | GT | GU | GW | GY | HK | HM | HN | HR | HT | HU | ID | IE | IL | IM | IN | IO | IQ | IR | IS | IT | JE | JM | JO | JP | KE | KG | KH | KI | KM | KN | KP | KR | KW | KY | KZ | LA | LB | LC | LI | LK | LR | LS | LT | LU | LV | LY | MA | MC | MD | ME | MF | MG | MH | MK | ML | MM | MN | MO | MP | MQ | MR | MS | MT | MU | MV | MW | MX | MY | MZ | NA | NC | NE | NF | NG | NI | NL | NO | NP | NR | NU | NZ | OM | PA | PE | PF | PG | PH | PK | PL | PM | PN | PR | PS | PT | PW | PY | QA | RE | RO | RS | RU | RW | SA | SB | SC | SD | SE | SG | SH | SI | SJ | SK | SL | SM | SN | SO | SR | SS | ST | SV | SX | SY | SZ | TC | TD | TF | TG | TH | TJ | TK | TL | TM | TN | TO | TR | TT | TV | TW | TZ | UA | UG | UM | US | UY | UZ | VA | VC | VE | VG | VI | VN | VU | WF | WS | YE | YT | ZA | ZM | ZW | No | Optional two-letter web-search country code. Omit to use the project’s country, or no country preference when a selected model cannot use it. Gemini always answers without a country. A country you name returns per-model errors for other models that cannot use it, without a paid call. |
| Name | Type | Required | Description |
|---|---|---|---|
prompt | string | null | No | — |
highlightBrand | string | null | null | No | — |
fetchedAt | string | null | No | — |
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
(
{
status: success,
model?: string | null,
modelName?: string | null | null,
text?: string | null,
citations?: {
url?: string | null,
domain?: string | null | null,
title?: string | null | null,
matchedBrand?: boolean | null
}[] | null,
fanOutQueries?: string[] | null,
brandMentioned?: boolean | null | null,
outputTokens?: number | null | null,
webSearch?: boolean | null,
webSearchCountryCode?: string | null | null
} | {
status: error,
model?: string | null,
errorCode?: string | null,
message?: string | null
}
)[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
export
aiVisibility.export
Export stored AI visibility observations as a CSV or JSON download link
Risk: read
await corsair.openseo.api.aiVisibility.export({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', format: 'csv', includeHistory: true });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
runId | string | null | No | Omit or null for the latest baseline/scheduled run. Reuse the returned runId for related source/answer reads. Do not use the string all. |
topic | string | null | No | Omit or null for all topics in the run. Filter by an exact saved topic name only when requested; do not use the string all. |
engines | (chatgpt | gemini | google_ai_overview | google_ai_mode | claude | perplexity)[] | null | No | Omit or null for all engines in one call. Provide one or more engines for an explicitly requested subset, or an empty array for no engines. Do not make separate calls for each engine or use the string all. |
promptId | string | null | No | Omit or null for all prompts in the run. Provide an exact prompt ID only when requested; includeHistory returns that prompt’s prior observations. Do not use the string all. |
includeHistory | boolean | No | — |
competitorGap | boolean | No | Use false for the initial review, overall sources and branded diagnostics. True restricts rows to answers where a competitor appears and your brand is absent; an empty gap subset does not mean answer details are missing. |
branded | all | neutral | branded | No | — |
cursor | string | null | No | Omit or null for the first page. Use only a returned nextCursor for another page; do not use the string all. |
limit | number | No | — |
format | json | csv | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
url?: string | null,
expiresAt?: string | null,
format?: string | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
generatePrompts
aiVisibility.generatePrompts
Generate topic and prompt suggestions for AI visibility tracking
Risk: destructive
await corsair.openseo.api.aiVisibility.generatePrompts({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
topic: 'Coffee subscriptions',
locationCode: 2840,
languageCode: 'en',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
topic | string | No | A saved topic to add prompts to, or a new topic name. Omit to let the model name a new topic. |
excludePrompts | string[] | No | — |
locationCode | number | Yes | — |
languageCode | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
topic?: string | null,
prompts?: string[] | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getAnswer
aiVisibility.getAnswer
Get one stored AI answer with its prompt, mentions and citations
Risk: read
await corsair.openseo.api.aiVisibility.getAnswer({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', observationId: 'e4b8c2a6-1d3f-4a97-8c5e-2f6a0b9d7e13' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
observationId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
observation?: {
id?: string | null,
runId?: string | null,
promptId?: string | null,
prompt?: string | null,
topic?: string | null,
branded?: boolean | null,
engine?: string | null,
status?: string | null,
brands?: {
name?: string | null,
domain?: string | null,
own?: boolean | null,
mentioned?: boolean | null,
cited?: boolean | null,
firstMention?: number | null | null
}[] | null,
answerStatus?: string | null | null,
citationCount?: number | null,
collectedAt?: string | null | null,
error?: string | null | null
} | null,
answerText?: string | null | null,
answerMarkdown?: string | null | null,
sources?: {
url?: string | null,
domain?: string | null,
title?: string | null | null,
position?: number | null
}[] | null,
mentions?: {
domain?: string | null,
spans?: {
start?: number | null,
end?: number | null
}[] | null
}[] | null,
requestedLocationCode?: number | null,
requestedLanguageCode?: string | null,
truncated?: boolean | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getResults
aiVisibility.getResults
Get how often the brand and competitors appear in AI answers for a run
Risk: read
await corsair.openseo.api.aiVisibility.getResults({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', competitorGap: true, limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
runId | string | null | No | Omit or null for the latest baseline/scheduled run. Reuse the returned runId for related source/answer reads. Do not use the string all. |
topic | string | null | No | Omit or null for all topics in the run. Filter by an exact saved topic name only when requested; do not use the string all. |
engines | (chatgpt | gemini | google_ai_overview | google_ai_mode | claude | perplexity)[] | null | No | Omit or null for all engines in one call. Provide one or more engines for an explicitly requested subset, or an empty array for no engines. Do not make separate calls for each engine or use the string all. |
promptId | string | null | No | Omit or null for all prompts in the run. Provide an exact prompt ID only when requested; includeHistory returns that prompt’s prior observations. Do not use the string all. |
includeHistory | boolean | No | — |
competitorGap | boolean | No | Use false for the initial review, overall sources and branded diagnostics. True restricts rows to answers where a competitor appears and your brand is absent; an empty gap subset does not mean answer details are missing. |
branded | all | neutral | branded | No | — |
cursor | string | null | No | Omit or null for the first page. Use only a returned nextCursor for another page; do not use the string all. |
limit | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
runId?: string | null | null,
run?: {
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
} | null | null,
rows?: {
id?: string | null,
runId?: string | null,
promptId?: string | null,
prompt?: string | null,
topic?: string | null,
branded?: boolean | null,
engine?: string | null,
status?: string | null,
brands?: {
name?: string | null,
domain?: string | null,
own?: boolean | null,
mentioned?: boolean | null,
cited?: boolean | null,
firstMention?: number | null | null
}[] | null,
answerStatus?: string | null | null,
citationCount?: number | null,
collectedAt?: string | null | null,
error?: string | null | null
}[] | null,
totalCount?: number | null,
nextCursor?: string | null | null,
summaries?: {
name?: string | null,
domain?: string | null,
own?: boolean | null,
answers?: number | null,
mentions?: number | null,
citations?: number | null,
positionTotal?: number | null,
positionCount?: number | null
}[] | null,
coverage?: {
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
noAnswer?: number | null
} | null,
appliedFilters?: {
topic?: string | null,
engines?: string[] | null,
competitorGap?: boolean | null,
branded?: string | null
} | null,
truncated?: boolean | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getRun
aiVisibility.getRun
Get the progress of an AI visibility check
Risk: read
await corsair.openseo.api.aiVisibility.getRun({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', runId: 'c7a3d9e1-5b2f-4c86-a0d4-9e1f3b7c5a28' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
runId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getSources
aiVisibility.getSources
List the pages or domains AI answers cited in a run
Risk: read
await corsair.openseo.api.aiVisibility.getSources({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
groupBy: 'domain',
ownership: 'competitor',
limit: 20,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
runId | string | null | No | Omit or null for the latest baseline/scheduled run. Reuse the returned runId for related source/answer reads. Do not use the string all. |
topic | string | null | No | Omit or null for all topics in the run. Filter by an exact saved topic name only when requested; do not use the string all. |
engines | (chatgpt | gemini | google_ai_overview | google_ai_mode | claude | perplexity)[] | null | No | Omit or null for all engines in one call. Provide one or more engines for an explicitly requested subset, or an empty array for no engines. Do not make separate calls for each engine or use the string all. |
promptId | string | null | No | Omit or null for all prompts in the run. Provide an exact prompt ID only when requested; includeHistory returns that prompt’s prior observations. Do not use the string all. |
includeHistory | boolean | No | — |
competitorGap | boolean | No | Use false for the initial review, overall sources and branded diagnostics. True restricts rows to answers where a competitor appears and your brand is absent; an empty gap subset does not mean answer details are missing. |
branded | all | neutral | branded | No | — |
cursor | string | null | No | Omit or null for the first page. Use only a returned nextCursor for another page; do not use the string all. |
limit | number | No | — |
groupBy | url | domain | No | — |
ownership | all | own | competitor | other | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
runId?: string | null | null,
rows?: {
key?: string | null,
url?: string | null | null,
domain?: string | null,
title?: string | null | null,
ownership?: string | null,
answerCount?: number | null,
promptCount?: number | null,
promptIds?: string[] | null,
engines?: {
engine?: string | null,
answerCount?: number | null
}[] | null,
observationIds?: string[] | null,
truncated?: boolean | null
}[] | null,
totalCount?: number | null,
nextCursor?: string | null | null,
coverage?: {
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
noAnswer?: number | null
} | null,
appliedFilters?: {
topic?: string | null,
engines?: string[] | null,
competitorGap?: boolean | null,
branded?: string | null,
ownership?: string | null
} | null,
groupBy?: string | null,
truncated?: boolean | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getTracker
aiVisibility.getTracker
Get a project’s AI visibility tracking setup: topics, prompts, engines and schedule
Risk: read
await corsair.openseo.api.aiVisibility.getTracker({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
configured?: boolean | null,
providerConfigured?: boolean | null,
tracker?: {
id?: string | null,
projectId?: string | null,
enabled?: boolean | null,
locationCode?: number | null,
languageCode?: string | null,
scheduleInterval?: string | null,
nextCheckAt?: string | null | null,
lastSkipReason?: string | null | null,
createdAt?: string | null
} | null | null,
topics?: string[] | null,
prompts?: {
id?: string | null,
text?: string | null,
topic?: string | null,
paused?: boolean | null,
archived?: boolean | null,
branded?: boolean | null,
hasResults?: boolean | null
}[] | null,
brands?: {
name?: string | null,
domain?: string | null,
own?: boolean | null
}[] | null,
engines?: string[] | null,
capabilities?: {
engine?: string | null,
label?: string | null,
unsupportedLocationCodes?: number[] | null,
maxPromptLength?: number | null,
note?: string | null,
modelApi?: boolean | null
}[] | null,
recentRuns?: {
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
}[] | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getTrend
aiVisibility.getTrend
Compare recent AI visibility with the previous period
Risk: read
await corsair.openseo.api.aiVisibility.getTrend({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', days: 28 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
days | 7 | 28 | 90 | No | Length of each period. Compares the latest N days with the N days before. |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
days?: number | null,
comparison?: string | null,
current?: {
start?: string | null,
end?: string | null,
coverage?: {
runs?: number | null,
expected?: number | null,
answered?: number | null,
noAnswer?: number | null,
failed?: number | null
} | null
} | null,
previous?: {
start?: string | null,
end?: string | null,
coverage?: {
runs?: number | null,
expected?: number | null,
answered?: number | null,
noAnswer?: number | null,
failed?: number | null
} | null
} | null,
mentions?: {
current?: number | null | null,
previous?: number | null | null,
change?: number | null | null,
matchedCells?: number | null,
currentCells?: number | null,
previousCells?: number | null
} | null,
citations?: {
current?: number | null | null,
previous?: number | null | null,
change?: number | null | null,
matchedCells?: number | null,
currentCells?: number | null,
previousCells?: number | null
} | null,
engines?: {
engine?: string | null,
mentions?: {
current?: number | null | null,
previous?: number | null | null,
change?: number | null | null,
matchedCells?: number | null,
currentCells?: number | null,
previousCells?: number | null
} | null,
citations?: {
current?: number | null | null,
previous?: number | null | null,
change?: number | null | null,
matchedCells?: number | null,
currentCells?: number | null,
previousCells?: number | null
} | null
}[] | null,
runs?: {
runId?: string | null,
createdAt?: string | null,
mentionRate?: number | null | null,
citationRate?: number | null | null,
coverage?: {
runs?: number | null,
expected?: number | null,
answered?: number | null,
noAnswer?: number | null,
failed?: number | null
} | null
}[] | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
researchPrompts
aiVisibility.researchPrompts
Find questions people ask AI about a keyword, with ChatGPT’s answers and sources
Risk: read
await corsair.openseo.api.aiVisibility.researchPrompts({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', keyword: 'coffee subscription' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
keyword | string | Yes | A short head term such as a tracker topic name. Exact multi-word phrases return few prompts. |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
keyword?: string | null,
prompts?: {
text?: string | null,
variants?: string[] | null,
sources?: {
domain?: string | null,
url?: string | null,
title?: string | null | null,
own?: boolean | null
}[] | null,
ownDomainCited?: boolean | null,
brandMentioned?: boolean | null,
tracked?: boolean | null
}[] | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
runCheck
aiVisibility.runCheck
Start a one-off paid AI visibility check now
Risk: destructive
await corsair.openseo.api.aiVisibility.runCheck({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', maxCostUsd: 0.5 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
maxCostUsd | number | Yes | Spending ceiling for this one check: runNowCostUsd from estimate_ai_visibility_cost. The check is refused if its current cost is higher. |
promptIds | string[] | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
saveTracker
aiVisibility.saveTracker
Create or update AI visibility tracking prompts, topics, engines and market
Risk: write
await corsair.openseo.api.aiVisibility.saveTracker({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
engines: ['chatgpt', 'perplexity'],
prompts: [{ text: 'What is the best coffee subscription?', topic: 'Coffee subscriptions' }],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
engines | (chatgpt | gemini | google_ai_overview | google_ai_mode | claude | perplexity)[] | No | — |
locationCode | number | No | Country for collection, as a DataForSEO location code from the project market list (2840 = United States). A new tracker defaults to the project’s market. Check capabilities for countries an engine cannot use. |
languageCode | string | No | Language for collection. Omit when changing country to use that country’s default language. |
prompts | object[] | No | — |
archivePromptIds | string[] | No | — |
prompts full type
prompts full type
{
id?: string,
text: string,
topic?: string,
paused?: boolean
}[]
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
state?: {
configured?: boolean | null,
providerConfigured?: boolean | null,
tracker?: {
id?: string | null,
projectId?: string | null,
enabled?: boolean | null,
locationCode?: number | null,
languageCode?: string | null,
scheduleInterval?: string | null,
nextCheckAt?: string | null | null,
lastSkipReason?: string | null | null,
createdAt?: string | null
} | null | null,
topics?: string[] | null,
prompts?: {
id?: string | null,
text?: string | null,
topic?: string | null,
paused?: boolean | null,
archived?: boolean | null,
branded?: boolean | null,
hasResults?: boolean | null
}[] | null,
brands?: {
name?: string | null,
domain?: string | null,
own?: boolean | null
}[] | null,
engines?: string[] | null,
capabilities?: {
engine?: string | null,
label?: string | null,
unsupportedLocationCodes?: number[] | null,
maxPromptLength?: number | null,
note?: string | null,
modelApi?: boolean | null
}[] | null,
recentRuns?: {
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
}[] | null
} | null,
created?: number | null,
updated?: number | null,
skipped?: number | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
setSchedule
aiVisibility.setSchedule
Turn scheduled AI visibility checks on, change the cadence or pause them
Risk: destructive
await corsair.openseo.api.aiVisibility.setSchedule({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
enabled: true,
scheduleInterval: 'weekly',
scheduleTime: {
weekday: 1,
hour: 9,
minute: 0,
timeZone: 'America/New_York',
},
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
enabled | boolean | Yes | — |
scheduleInterval | daily | weekly | monthly | No | Cadence when enabling. Defaults to the saved schedule, or weekly. Ignored when pausing. |
scheduleTime | object | No | Run time when enabling. Omit to keep the current next check when the cadence is unchanged, or to pick a time between 04:00 and 10:00 UTC. |
scheduleTime full type
scheduleTime full type
{
weekday?: number,
hour: number,
minute: number,
timeZone?: string
}
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
data | object | null | No | — |
code | string | null | No | — |
message | string | null | No | — |
recovery | string | null | No | — |
runId | string | null | No | — |
meta | object | null | No | — |
data full type
data full type
{
state?: {
configured?: boolean | null,
providerConfigured?: boolean | null,
tracker?: {
id?: string | null,
projectId?: string | null,
enabled?: boolean | null,
locationCode?: number | null,
languageCode?: string | null,
scheduleInterval?: string | null,
nextCheckAt?: string | null | null,
lastSkipReason?: string | null | null,
createdAt?: string | null
} | null | null,
topics?: string[] | null,
prompts?: {
id?: string | null,
text?: string | null,
topic?: string | null,
paused?: boolean | null,
archived?: boolean | null,
branded?: boolean | null,
hasResults?: boolean | null
}[] | null,
brands?: {
name?: string | null,
domain?: string | null,
own?: boolean | null
}[] | null,
engines?: string[] | null,
capabilities?: {
engine?: string | null,
label?: string | null,
unsupportedLocationCodes?: number[] | null,
maxPromptLength?: number | null,
note?: string | null,
modelApi?: boolean | null
}[] | null,
recentRuns?: {
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
}[] | null
} | null,
run?: {
id?: string | null,
status?: string | null,
trigger?: string | null,
expected?: number | null,
completed?: number | null,
failed?: number | null,
pending?: number | null,
createdAt?: string | null,
completedAt?: string | null | null,
pollAfterSeconds?: number | null
} | null | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
updateResearchKeywords
aiVisibility.updateResearchKeywords
Add or remove a project’s saved Prompt Research keywords
Risk: write
await corsair.openseo.api.aiVisibility.updateResearchKeywords({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
add: ['coffee subscription'],
remove: ['coffee pods'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
remove | string[] | No | Saved keywords to take off the list. Case and spacing don’t matter. |
add | string[] | No | Keywords to put at the top of the list, such as replacements for the removed ones. |
| Name | Type | Required | Description |
|---|---|---|---|
keywords | string[] | null | No | — |
trackedTopics | string[] | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Backlinks
list
backlinks.list
List a domain’s or page’s individual backlinks with anchors and authority, paginated
Risk: read
await corsair.openseo.api.backlinks.list({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
target: 'bluebottlecoffee.com',
pageSize: 50,
sortField: 'rank',
sortOrder: 'desc',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
target | string | Yes | Domain or URL to analyze (e.g. ‘example.com’ or ‘https://example.com/blog’). |
scope | exact_url | subfolder | domain | subdomains | page | No | Research scope: ‘domain’ (hostname without subdomains), ‘subdomains’ (hostname plus all subdomains), ‘subfolder’ (path and its children), or ‘exact_url’ (one page). Defaults to ‘subdomains’ for root inputs and ‘subfolder’ when the input has a path. ‘page’ is a deprecated alias of ‘exact_url’. Subfolder counts are computed from filtered backlink totals; rank, trends, and the referring-domains breakdown are unavailable for subfolders. |
page | number | No | 1-indexed results page. Defaults to 1. |
pageSize | number | No | Rows per page. Allowed values: 50, 100, or 200. |
sortField | rank | domainRank | spamScore | firstSeen | No | Backlink row sort field. |
sortOrder | asc | desc | No | Sort direction. |
filters | object | No | Backlink row filters: include/exclude source URL terms, authority/spam ranges, dofollow/nofollow, lost/broken visibility, or exact domainFrom. |
mode | one_per_domain | as_is | No | DataForSEO backlink grouping: one_per_domain returns each referring domain’s strongest link; as_is returns individual backlink rows. |
hideSpam | boolean | No | Hide backlinks with Spam scores of 40 or higher. Defaults to true. Unknown scores remain visible. This is a heuristic, not a judgment about a link. Set false to inspect all matching links. True leaves six user filter conditions (two for subfolders); false allows eight (four for subfolders). Each include/exclude term and numeric bound counts separately. |
filters full type
filters full type
{
include?: string,
exclude?: string,
minDomainRank?: number | string,
maxDomainRank?: number | string,
minLinkAuthority?: number | string,
maxLinkAuthority?: number | string,
minSpamScore?: number | string,
maxSpamScore?: number | string,
linkType?: dofollow | nofollow,
hideLost?: boolean,
hideBroken?: boolean,
domainFrom?: string
}
| Name | Type | Required | Description |
|---|---|---|---|
target | string | null | No | — |
scope | string | null | No | — |
backlinks | object | null | No | — |
meta | object | null | No | — |
backlinks full type
backlinks full type
{
rows?: {
}[] | null,
totalCount?: number | null | null,
hasMore?: boolean | null,
page?: number | null,
pageSize?: number | null,
fetchedAt?: string | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
overview
backlinks.overview
Summarize a domain’s or page’s backlinks, referring domains and authority
Risk: read
await corsair.openseo.api.backlinks.overview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', target: 'bluebottlecoffee.com' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
target | string | Yes | Domain or URL to analyze (e.g. ‘example.com’ or ‘https://example.com/blog’). |
scope | exact_url | subfolder | domain | subdomains | page | No | Research scope: ‘domain’ (hostname without subdomains), ‘subdomains’ (hostname plus all subdomains), ‘subfolder’ (path and its children), or ‘exact_url’ (one page). Defaults to ‘subdomains’ for root inputs and ‘subfolder’ when the input has a path. ‘page’ is a deprecated alias of ‘exact_url’. Subfolder counts are computed from filtered backlink totals; rank, trends, and the referring-domains breakdown are unavailable for subfolders. |
hideSpam | boolean | No | Filter out spammy referring domains. Defaults to true. |
| Name | Type | Required | Description |
|---|---|---|---|
target | string | null | No | — |
scope | string | null | No | — |
scopeNote | string | null | No | — |
overview | object | null | No | — |
referringDomains | object | null | No | — |
meta | object | null | No | — |
overview full type
overview full type
{
} | null
referringDomains full type
referringDomains full type
{
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Domains
keywords
domains.keywords
List the organic keywords a domain ranks for, with position and metrics
Risk: read
await corsair.openseo.api.domains.keywords({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', domain: 'bluebottlecoffee.com' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
domain | string | Yes | Competitor or reference domain or URL to extract keywords from. |
scope | exact_url | subfolder | domain | subdomains | No | Research scope: ‘domain’ (hostname without subdomains), ‘subdomains’ (hostname plus all subdomains), ‘subfolder’ (path and its children), or ‘exact_url’ (one page). Defaults to ‘subdomains’ for root inputs and ‘subfolder’ when the input has a path. |
locationCode | number | No | DataForSEO country location code (e.g. 2840 United States, 2826 United Kingdom). Defaults to the project’s default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
| Name | Type | Required | Description |
|---|---|---|---|
keywords | object[] | null | No | — |
target | string | null | No | — |
scope | string | null | No | — |
meta | object | null | No | — |
keywords full type
keywords full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
overview
domains.overview
Estimate a domain’s monthly organic traffic and ranking keyword count
Risk: read
await corsair.openseo.api.domains.overview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', domain: 'bluebottlecoffee.com' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
domain | string | Yes | Domain or URL to analyze (e.g. ‘example.com’). |
scope | exact_url | subfolder | domain | subdomains | No | Research scope: ‘domain’ (hostname without subdomains), ‘subdomains’ (hostname plus all subdomains), ‘subfolder’ (path and its children), or ‘exact_url’ (one page). Defaults to ‘subdomains’ for root inputs and ‘subfolder’ when the input has a path. Overview metrics always cover the hostname plus subdomains; narrower scopes are labeled accordingly — use get_ranked_keywords with a scope for scoped keyword data. |
includeSubdomains | boolean | No | Deprecated: use scope (‘subdomains’ or ‘domain’) instead. |
locationCode | number | No | DataForSEO country location code (e.g. 2840 United States, 2826 United Kingdom). Defaults to the project’s default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | null | No | — |
scope | string | null | No | — |
displayTarget | string | null | No | — |
organicTraffic | number | null | null | No | — |
organicKeywords | number | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
rankedKeywords
domains.rankedKeywords
List the keywords a domain or page ranks for in one country, with ranking URL and traffic
Risk: read
await corsair.openseo.api.domains.rankedKeywords({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
target: 'bluebottlecoffee.com',
maxRank: 10,
limit: 50,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
target | string | Yes | Domain (no protocol/www) or absolute page URL to list ranked keywords for. |
scope | exact_url | subfolder | domain | subdomains | No | Research scope: ‘domain’ (hostname without subdomains), ‘subdomains’ (hostname plus all subdomains), ‘subfolder’ (path and its children), or ‘exact_url’ (one page). Defaults to ‘subdomains’ for root inputs and ‘subfolder’ when the input has a path. |
market | object | No | Legacy US selector. Prefer locationCode/languageCode for any Labs market. Explicit locationCode takes precedence; otherwise omitted = the project’s default market. |
locationCode | number | No | Country-level DataForSEO Labs location code. Defaults to the project’s market; takes precedence over the legacy market object. |
languageCode | string | No | Language for locationCode. Defaults to that location’s primary language when locationCode overrides the project market. |
resultTypes | (organic | paid | featured_snippet | local_pack | ai_overview_reference)[] | No | SERP result types to include. Defaults to organic and paid. |
includeSubdomains | boolean | No | Deprecated: use scope (‘subdomains’ or ‘domain’) instead. |
minSearchVolume | number | No | Only return keywords with at least this monthly search volume. |
maxRank | number | No | Only return keywords ranking at this position or better. |
excludeBrandTerms | string[] | No | Exclude keywords containing any of these brand terms. |
sortBy | rank | search_volume | traffic_estimate | cpc | No | Sort order for returned rows. Defaults to search_volume. |
limit | number | No | Maximum rows to return (1-100). Defaults to 50. |
offset | number | No | Rows to skip for pagination. |
market full type
market full type
{
country?: US | USA | United States | United States of America
}
| Name | Type | Required | Description |
|---|---|---|---|
keywords | object[] | null | No | — |
totalCount | number | null | null | No | — |
target | string | null | No | — |
scope | string | null | No | — |
meta | object | null | No | — |
keywords full type
keywords full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Google Analytics
audienceBreakdown
googleAnalytics.audienceBreakdown
Break down visitors by device, country or new versus returning
Risk: read
await corsair.openseo.api.googleAnalytics.audienceBreakdown({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'device' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
breakdown | device | country | new_vs_returning | No | — |
channel | organic_search | all | No | — |
comparePreviousPeriod | boolean | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
ecommercePerformance
googleAnalytics.ecommercePerformance
Get GA4 ecommerce item views, add-to-carts, purchases and revenue
Risk: read
await corsair.openseo.api.googleAnalytics.ecommercePerformance({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'item', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
breakdown | item | landing_page | No | — |
onlyWithTransactions | boolean | No | — |
channel | organic_search | all | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
keyEvents
googleAnalytics.keyEvents
Get GA4 key events (conversions) by event or organic landing page
Risk: read
await corsair.openseo.api.googleAnalytics.keyEvents({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'event', comparePreviousPeriod: true });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
breakdown | event | event_and_landing_page | No | — |
channel | organic_search | all | No | — |
comparePreviousPeriod | boolean | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
listProperties
googleAnalytics.listProperties
List the GA4 properties of the connected Google accounts
Risk: read
await corsair.openseo.api.googleAnalytics.listProperties({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
accounts | object[] | null | No | — |
meta | object | null | No | — |
accounts full type
accounts full type
{
accountId?: string | null,
email?: string | null | null,
requiresReconnect?: boolean | null,
propertiesUnavailable?: boolean | null,
properties?: {
propertyId?: string | null,
displayName?: string | null,
accountDisplayName?: string | null,
isSelected?: boolean | null
}[] | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
measurementHealth
googleAnalytics.measurementHealth
Check how Google Analytics is set up on the connected property
Risk: read
await corsair.openseo.api.googleAnalytics.measurementHealth({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
summary | object | null | No | — |
issues | string[] | null | No | — |
webStreams | object[] | null | No | — |
otherStreams | object[] | null | No | — |
keyEvents | object[] | null | No | — |
customDefinitions | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
summary full type
summary full type
{
} | null
webStreams full type
webStreams full type
{
}[] | null
otherStreams full type
otherStreams full type
{
}[] | null
keyEvents full type
keyEvents full type
{
}[] | null
customDefinitions full type
customDefinitions full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
organicLandingPages
googleAnalytics.organicLandingPages
Get the landing pages that receive organic search traffic
Risk: read
await corsair.openseo.api.googleAnalytics.organicLandingPages({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
organicOverview
googleAnalytics.organicOverview
Get top-line organic search sessions, users and key events with a trend
Risk: read
await corsair.openseo.api.googleAnalytics.organicOverview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', trend: 'weekly' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
trend | daily | weekly | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
current | object | null | No | — |
previous | object | null | No | — |
comparison | object | null | No | — |
trend | object[] | null | No | — |
diagnostics | object[] | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
current full type
current full type
{
} | null | null
previous full type
previous full type
{
} | null | null
comparison full type
comparison full type
{
} | null
trend full type
trend full type
{
}[] | null
diagnostics full type
diagnostics full type
{
}[] | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
pagePerformance
googleAnalytics.pagePerformance
Get page views, users, engagement and key events per page
Risk: read
await corsair.openseo.api.googleAnalytics.pagePerformance({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', channel: 'organic_search', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
includeDate | boolean | No | — |
channel | organic_search | all | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
setProperty
googleAnalytics.setProperty
Set which GA4 property a project reads
Risk: write
await corsair.openseo.api.googleAnalytics.setProperty({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', propertyId: 'properties/412345678', ga4AccountId: 'f3c9a1e7-2d5b-4f80-9b6e-4a2d8c0f6e35' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
propertyId | string | Yes | GA4 property exactly as list_google_analytics_properties returns it (e.g. “properties/123456789”). |
ga4AccountId | string | Yes | accountId of the connected Google account from the list tool. |
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
projectId | string | null | No | — |
propertyId | string | null | No | — |
ga4AccountId | string | null | No | — |
propertyDisplayName | string | null | null | No | — |
connectedByEmail | string | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
siteSearch
googleAnalytics.siteSearch
Get the terms visitors search for on the site
Risk: read
await corsair.openseo.api.googleAnalytics.siteSearch({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
trafficAcquisition
googleAnalytics.trafficAcquisition
Compare traffic by channel group, source/medium or campaign
Risk: read
await corsair.openseo.api.googleAnalytics.trafficAcquisition({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'channel_group' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
offset | number | No | — |
breakdown | channel_group | source_medium | campaign | No | — |
comparePreviousPeriod | boolean | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalRowCount | number | null | No | — |
rows | object[] | null | No | — |
pageInfo | object | null | No | — |
reportMetadata | object | null | No | — |
warnings | string[] | null | No | — |
quota | object | null | No | — |
comparison | object | null | No | — |
ecommerceActivity | object | null | No | — |
siteSearchActivity | object | null | No | — |
diagnostics | object[] | null | No | — |
diagnosticCoverage | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
pageInfo full type
pageInfo full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
comparison full type
comparison full type
{
} | null
ecommerceActivity full type
ecommerceActivity full type
{
} | null
siteSearchActivity full type
siteSearchActivity full type
{
} | null
diagnostics full type
diagnostics full type
{
}[] | null
diagnosticCoverage full type
diagnosticCoverage full type
{
} | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
Index Now
submitUrls
indexNow.submitUrls
Notify IndexNow search engines (Bing, Yandex and others) that pages changed
Risk: destructive · Irreversible
await corsair.openseo.api.indexNow.submitUrls({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
urls: ['https://acmecoffee.com/blog/cold-brew-guide'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
urls | string[] | Yes | Absolute URLs on the project’s website (any subdomain) that were added, changed, redirected or removed. |
| Name | Type | Required | Description |
|---|---|---|---|
key | string | null | No | — |
keyCreated | boolean | null | No | — |
hosts | object[] | null | No | — |
skipped | string[] | null | No | — |
meta | object | null | No | — |
hosts full type
hosts full type
{
host?: string | null,
urlCount?: number | null,
status?: string | null,
message?: string | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Keywords
listSaved
keywords.listSaved
List a project’s saved keywords with cached volume, difficulty, CPC and tags
Risk: read
await corsair.openseo.api.keywords.listSaved({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 50 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
search | string | No | Optional keyword text filter. |
tags | string[] | No | Optional tag-name filters. Multiple tags match ANY tag. |
limit | 50 | 100 | 250 | No | Maximum rows to return. Defaults to 100. |
| Name | Type | Required | Description |
|---|---|---|---|
rows | object[] | null | No | — |
totalCount | number | null | No | — |
tags | object[] | null | No | — |
meta | object | null | No | — |
rows full type
rows full type
{
id?: string | null,
keyword?: string | null,
searchVolume?: number | null | null,
keywordDifficulty?: number | null | null,
cpc?: number | null | null,
competition?: number | null | null,
intent?: string | null | null,
tags?: string[] | null
}[] | null
tags full type
tags full type
{
name?: string | null,
keywordCount?: number | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
metrics
keywords.metrics
Get search volume, difficulty, intent, CPC and trends for a list of keywords
Risk: read
await corsair.openseo.api.keywords.metrics({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
keywords: ['coffee subscription', 'whole bean coffee'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
keywords | string[] | Yes | Keywords to fetch metrics for (1-700). |
locationCode | number | No | DataForSEO country location code (e.g. 2840 United States, 2826 United Kingdom). Defaults to the project’s default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
includeMonthlyTrends | boolean | No | Include monthly search-volume trend rows. Defaults to true. |
includeClickstreamData | boolean | No | Refine search volumes with clickstream data, which disaggregates Google Ads’ grouped close-variant volumes (plurals/misspellings). DOUBLES the credit cost of the call. Default false. No effect for countries served from Google Ads data. |
sortBy | search_volume | keyword_difficulty | cpc | competition | No | Sort order for returned rows. Defaults to search_volume. |
| Name | Type | Required | Description |
|---|---|---|---|
keywords | object[] | null | No | — |
meta | object | null | No | — |
keywords full type
keywords full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
removeSaved
keywords.removeSaved
Delete saved keywords from a project by ID
Risk: destructive · Irreversible
await corsair.openseo.api.keywords.removeSaved({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
savedKeywordIds: ['b2f6e0d4-8a1c-4f3e-9d27-5c4a1e8b3f60'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
savedKeywordIds | string[] | Yes | Saved-keyword row IDs to delete. Use the id values returned by list_saved_keywords. |
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | null | No | — |
requested | number | null | No | — |
deletedCount | number | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
research
keywords.research
Find keyword ideas for 1-5 seed keywords with volume, difficulty, CPC and intent
Risk: read
await corsair.openseo.api.keywords.research({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
seeds: [{ seed: 'coffee subscription' }],
resultLimit: 150,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
seeds | object[] | Yes | 1-5 seed keywords. Each seed is researched independently and returns related keywords with volume/difficulty/CPC. Bulk-friendly — prefer this over multiple single-seed calls. |
resultLimit | 150 | 300 | 500 | No | Max keywords returned per seed. Defaults to 150. Auto mode blends two sources; duplicate keywords across sources appear once. |
includeClickstreamData | boolean | No | Refine search volumes with clickstream data, which disaggregates Google Ads’ grouped close-variant volumes (plurals/misspellings). DOUBLES the credit cost of each seed. Default false (standard Google-Ads-derived volumes). No effect for countries served from Google Ads data. |
groupKeywords | boolean | No | Include similar keyword variants that can share volume, CPC, and competition. Default false returns only core keywords (DataForSEO ignore_synonyms=true). True includes variants (ignore_synonyms=false). This filters keywords, not metric estimates. Do not sum shared volumes. No effect for countries served from Google Ads data. |
seeds full type
seeds full type
{
seed: string,
locationCode?: number,
languageCode?: string,
locationName?: string
}[]
| Name | Type | Required | Description |
|---|---|---|---|
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
(
{
seed?: string | null,
ok: true,
rowCount?: number | null,
source?: string | null,
usedFallback?: boolean | null,
rows?: {
}[] | null
} | {
seed?: string | null,
ok: false,
error?: string | null
}
)[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
save
keywords.save
Save keywords to a project, optionally with metrics and tags
Risk: write
await corsair.openseo.api.keywords.save({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
keywords: ['coffee subscription', 'best coffee beans'],
tags: ['subscriptions'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
keywords | string[] | Yes | Keywords to save (1-100). |
metrics | object[] | No | Optional metrics for the saved keywords. Copy keyword, searchVolume, keywordDifficulty, cpc, competition, and intent from research_keywords or get_keyword_metrics rows. monthlySearches is optional. Match each metric using its keyword field. |
tags | string[] | No | Optional tags to attach to every saved keyword. Ask the user for explicit confirmation before using this, especially when saving many keywords or creating new tag names. |
tagMode | append | replace | No | How to apply tags. Defaults to append. Use replace to remove existing tags from these saved keywords before applying the provided tags. |
locationCode | number | No | DataForSEO country location code (e.g. 2840 United States, 2826 United Kingdom). Defaults to the project’s default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
metrics full type
metrics full type
{
keyword: string,
searchVolume?: number | null,
cpc?: number | null,
competition?: number | null,
keywordDifficulty?: number | null,
intent?: informational | commercial | transactional | navigational | unknown | null,
monthlySearches?: {
year: number,
month: number,
searchVolume: number
}[]
}[]
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | null | No | — |
savedCount | number | null | No | — |
keywords | string[] | null | No | — |
tags | string[] | null | No | — |
tagMode | string | null | No | — |
locationCode | number | null | No | — |
languageCode | string | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
suggestions
keywords.suggestions
Suggest up to 10 seed keywords to research next from Search Console and saved keywords
Risk: read
await corsair.openseo.api.keywords.suggestions({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
suggestions | object[] | null | No | — |
searchConsoleConnected | boolean | null | No | — |
meta | object | null | No | — |
suggestions full type
suggestions full type
{
keyword?: string | null,
reason?: string | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Local
businessProfile
local.businessProfile
Get a Google Business Profile by name, CID or place ID
Risk: read
await corsair.openseo.api.local.businessProfile({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
businessName: 'Houndstooth Coffee',
near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
businessName | string | No | Business name as it appears on Google. Supply exactly one of businessName, cid, or placeId. |
cid | string | No | Google-defined business CID (from get_local_serp_results rows). Most precise identifier. |
placeId | string | No | Google Maps place_id (from get_local_serp_results rows). |
near | object | No | Coordinate to search from. Use it when the business name is ambiguous; otherwise locationCode is enough. |
locationCode | number | No | DataForSEO location code. Ignored when near is set; otherwise defaults to the project’s market. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
near full type
near full type
{
latitude: number,
longitude: number,
radiusKm?: number
}
| Name | Type | Required | Description |
|---|---|---|---|
profile | object | null | No | — |
meta | object | null | No | — |
profile full type
profile full type
{
} | null | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
businessQuestions
local.businessQuestions
Get the questions and answers on a Google Business Profile
Risk: read
await corsair.openseo.api.local.businessQuestions({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
businessName: 'Houndstooth Coffee',
near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
businessName | string | No | Business name as it appears on Google. Supply exactly one of businessName, cid, or placeId. |
cid | string | No | Google-defined business CID (from get_local_serp_results rows). Most precise identifier. |
placeId | string | No | Google Maps place_id (from get_local_serp_results rows). |
near | object | Yes | Coordinate and radius to search around. |
depth | number | No | Maximum Q&A rows to fetch (1-100). Defaults to 20. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
near full type
near full type
{
latitude: number,
longitude: number,
radiusKm: number
}
| Name | Type | Required | Description |
|---|---|---|---|
questions | object[] | null | No | — |
meta | object | null | No | — |
questions full type
questions full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
businessReviews
local.businessReviews
Get a business’s Google reviews with ratings and owner replies
Risk: read
await corsair.openseo.api.local.businessReviews({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
businessName: 'Houndstooth Coffee',
near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
depth: 20,
sortBy: 'newest',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
businessName | string | No | Business name as it appears on Google. Supply exactly one of businessName, cid, or placeId. |
cid | string | No | Google-defined business CID (from get_local_serp_results rows). Most precise identifier. |
placeId | string | No | Google Maps place_id (from get_local_serp_results rows). |
near | object | No | Coordinate to search from. Use it when the business name is ambiguous; otherwise locationCode is enough. |
locationCode | number | No | DataForSEO location code. Ignored when near is set; otherwise defaults to the project’s market. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
depth | number | No | Number of reviews to collect (10-200). Defaults to 20. Billed per 10 reviews (per 20 when includeOtherSources is true). |
sortBy | newest | highest_rating | lowest_rating | relevant | No | Review sort order. Defaults to newest. Ignored when includeOtherSources is true — the extended endpoint has no sort option. |
includeOtherSources | boolean | No | Also collect the reviews Google shows from other sites (Yelp, Tripadvisor, Trustpilot). Defaults to false. Costs more per review and cannot be sorted. |
taskId | string | No | Resume a previous call that returned status “processing”. Pass back the taskId exactly as returned (format “google:<id>” or “extended:<id>”); it selects the right endpoint on its own. Resuming charges no extra credits. |
near full type
near full type
{
latitude: number,
longitude: number,
radiusKm?: number
}
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
taskId | string | null | No | — |
reviews | object[] | null | No | — |
totals | object | null | No | — |
meta | object | null | No | — |
reviews full type
reviews full type
{
}[] | null
totals full type
totals full type
{
} | null | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
businessUpdates
local.businessUpdates
Get the posts published on a Google Business Profile
Risk: read
await corsair.openseo.api.local.businessUpdates({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
businessName: 'Houndstooth Coffee',
near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
businessName | string | No | Business name as it appears on Google. Supply exactly one of businessName, cid, or placeId. |
cid | string | No | Google-defined business CID (from get_local_serp_results rows). Most precise identifier. |
placeId | string | No | Google Maps place_id (from get_local_serp_results rows). |
near | object | No | Coordinate to search from. Use it when the business name is ambiguous; otherwise locationCode is enough. |
locationCode | number | No | DataForSEO location code. Ignored when near is set; otherwise defaults to the project’s market. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
depth | number | No | Number of posts to collect (10-100). Defaults to 10. |
taskId | string | No | Resume a previous call that returned status “processing”. Pass back the taskId exactly as returned. Resuming charges no extra credits. |
near full type
near full type
{
latitude: number,
longitude: number,
radiusKm?: number
}
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
taskId | string | null | No | — |
updates | object[] | null | No | — |
meta | object | null | No | — |
updates full type
updates full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
listCategories
local.listCategories
List Google Business categories ranked by how many businesses use them
Risk: read
await corsair.openseo.api.local.listCategories({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', query: 'coffee', limit: 10 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
query | string | No | Case-insensitive substring to match against category slugs (e.g. ‘plumb’). |
limit | number | No | Maximum categories to return (1-200). Defaults to 50. |
| Name | Type | Required | Description |
|---|---|---|---|
categories | object[] | null | No | — |
meta | object | null | No | — |
categories full type
categories full type
{
category?: string | null,
businessCount?: number | null | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
rankGrid
local.rankGrid
Map a business’s Google Maps rank across a grid of points around a center
Risk: read
await corsair.openseo.api.local.rankGrid({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
keyword: 'coffee shop',
target: { name: 'Houndstooth Coffee' },
center: { latitude: 30.2672, longitude: -97.7431 },
gridSize: 3,
spacingKm: 1,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
keyword | string | Yes | Search query to run on Google Maps at every grid point. |
target | object | Yes | The business to locate in each result set. Supply at least one of cid, placeId, or name. |
center | object | Yes | Coordinate the grid is centered on (usually the storefront). |
gridSize | 3 | 5 | No | Grid width: 3 (9 searches) or 5 (25 searches). Defaults to 3. |
spacingKm | number | No | Distance between neighbouring grid points, in km. Defaults to 2. |
device | desktop | mobile | No | Device the SERP is rendered for. Defaults to mobile. |
zoom | number | No | Map zoom every point is searched at. Defaults to a zoom derived from spacingKm and latitude so each point’s viewport spans the grid spacing; override only when you need a specific viewport. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
target full type
target full type
{
cid?: string,
placeId?: string,
name?: string
}
center full type
center full type
{
latitude: number,
longitude: number
}
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
pointsReady | number | null | No | — |
pointsTotal | number | null | No | — |
retryAfterSeconds | number | null | No | — |
grid | object[] | null | No | — |
summary | object | null | No | — |
matchedBusiness | object | null | No | — |
meta | object | null | No | — |
grid full type
grid full type
{
row?: number | null,
col?: number | null,
latitude?: number | null,
longitude?: number | null,
rank?: number | null | null,
resultsCount?: number | null,
topResult?: {
title?: string | null | null,
cid?: string | null | null
} | null | null,
error?: boolean | null
}[] | null
summary full type
summary full type
{
pointsSearched?: number | null,
pointsFound?: number | null,
averageRank?: number | null | null,
top3Count?: number | null,
top10Count?: number | null
} | null
matchedBusiness full type
matchedBusiness full type
{
title?: string | null | null,
cid?: string | null | null,
placeId?: string | null | null
} | null | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
searchBusinesses
local.searchBusinesses
Search local business listings near a coordinate
Risk: read
await corsair.openseo.api.local.searchBusinesses({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
query: 'coffee shop',
near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 5 },
minRating: 4,
limit: 20,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
query | string | No | Text the business name must contain, such as a trade word. For a business type, use categories. |
near | object | Yes | Coordinate and radius to search around. |
categories | string[] | No | Business categories to filter by (e.g. ‘pizza_restaurant’). |
minRating | number | No | Only return businesses rated at least this (1-5). |
minReviews | number | No | Only return businesses with at least this many Google reviews. |
isClaimed | boolean | No | Filter by whether the listing is claimed by its owner. false surfaces unclaimed listings (outreach prospects). |
sortBy | relevance | rating | reviews | No | Sort order for returned rows. Defaults to relevance. |
limit | number | No | Maximum businesses to return (1-50). Defaults to 20. |
offset | number | No | Rows to skip for pagination. |
near full type
near full type
{
latitude: number,
longitude: number,
radiusKm: number
}
| Name | Type | Required | Description |
|---|---|---|---|
businesses | object[] | null | No | — |
meta | object | null | No | — |
businesses full type
businesses full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
serpResults
local.serpResults
Get Google Maps or Local Finder results for a keyword from a coordinate
Risk: read
await corsair.openseo.api.local.serpResults({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
keyword: 'coffee shop',
near: { latitude: 30.2672, longitude: -97.7431 },
searchType: 'maps',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
keyword | string | Yes | Search query to run on Google Maps or Local Finder. |
near | object | Yes | Coordinate (and optional map zoom) the SERP is fetched from. |
searchType | maps | local_finder | No | Which local SERP to fetch. Defaults to maps. |
device | desktop | mobile | No | Device the SERP is rendered for. Defaults to mobile, matching get_local_rank_grid. |
depth | number | No | Number of results to fetch (1-100). Defaults to 20. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
near full type
near full type
{
latitude: number,
longitude: number,
zoom?: number
}
| Name | Type | Required | Description |
|---|---|---|---|
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Projects
create
projects.create
Create a project with a name and optional domain and market
Risk: write
await corsair.openseo.api.projects.create({
name: 'Acme Coffee',
domain: 'acmecoffee.com',
locationCode: 2840,
languageCode: 'en',
});
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Project name (1-120 characters). |
domain | string | No | Optional root domain for the project, e.g. “example.com” (host only, no scheme or path). Sets the default target for domain, backlink, and rank tools. |
locationCode | number | No | Optional DataForSEO location code for the project’s default market (e.g. 2840 = United States, 2504 = Morocco). Falls back to the organization default when omitted. |
languageCode | string | No | Optional language code (e.g. “en”, “fr”). Requires locationCode; derived from the location when omitted. |
| Name | Type | Required | Description |
|---|---|---|---|
project | object | null | No | — |
meta | object | null | No | — |
project full type
project full type
{
id?: string | null,
name?: string | null,
domain?: string | null | null,
locationCode?: number | null,
languageCode?: string | null,
url?: string | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
getContext
projects.getContext
Get a project’s shared memory: overview, goal, positioning, competitors and key pages
Risk: read
await corsair.openseo.api.projects.getContext({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
sections | object[] | null | No | — |
missingSections | string[] | null | No | — |
customSections | object[] | null | No | — |
competitors | object[] | null | No | — |
keyPages | object[] | null | No | — |
researchLog | object[] | null | No | — |
reportTemplates | object[] | null | No | — |
meta | object | null | No | — |
sections full type
sections full type
{
}[] | null
customSections full type
customSections full type
{
}[] | null
competitors full type
competitors full type
{
}[] | null
keyPages full type
keyPages full type
{
}[] | null
researchLog full type
researchLog full type
{
}[] | null
reportTemplates full type
reportTemplates full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
list
projects.list
List projects with their ID, name, domain and default market
Risk: read
await corsair.openseo.api.projects.list({});
| Name | Type | Required | Description |
|---|---|---|---|
projects | object[] | null | No | — |
meta | object | null | No | — |
projects full type
projects full type
{
id?: string | null,
name?: string | null,
domain?: string | null | null,
locationCode?: number | null,
languageCode?: string | null,
url?: string | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
researchWebsite
projects.researchWebsite
Research a project’s website to draft its brand, overview, competitors and prompt topics
Risk: destructive
await corsair.openseo.api.projects.researchWebsite({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', website: 'https://acmecoffee.com' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | — |
website | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | No | — |
domain | string | null | No | — |
overview | string | null | No | — |
competitors | object[] | null | No | — |
preserveCompetitors | boolean | null | No | — |
suggestedTopics | object[] | null | No | — |
suggestedKeywords | string[] | null | No | — |
meta | object | null | No | — |
competitors full type
competitors full type
{
}[] | null
suggestedTopics full type
suggestedTopics full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
saveWebsiteSetup
projects.saveWebsiteSetup
Save a drafted website setup (brand, overview, competitors, topics) to a project
Risk: write
await corsair.openseo.api.projects.saveWebsiteSetup({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
name: 'Acme Coffee',
domain: 'acmecoffee.com',
overview: 'Specialty coffee roaster selling beans and subscriptions online.',
competitors: [{ name: 'Blue Bottle', domain: 'bluebottlecoffee.com' }],
});
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | — |
domain | string | Yes | — |
overview | string | Yes | — |
competitors | object[] | Yes | — |
projectId | string | Yes | — |
suggestedTopics | object[] | No | — |
suggestedKeywords | string[] | No | — |
competitors full type
competitors full type
{
name: string,
domain: string,
notes?: string
}[]
suggestedTopics full type
suggestedTopics full type
{
name: string,
prompts: string[]
}[]
| Name | Type | Required | Description |
|---|---|---|---|
project | object | null | No | — |
meta | object | null | No | — |
project full type
project full type
{
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
updateContext
projects.updateContext
Add, edit or delete entries in a project’s shared memory
Risk: write
await corsair.openseo.api.projects.updateContext({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
updates: [{ section: 'current_goal', content: 'Rank in the top 3 for coffee subscription keywords by Q2.' }],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
updates | object[] | Yes | Patch ops, applied in order. Set the name AI visibility looks for in answers with {brandName: “Acme”}, after the user confirms it; an empty string goes back to the project name. Clear a standard section with {section: “current_goal”, content: ""}; delete a custom section with {deleteCustomSection: “slug”}; removeCompetitors takes domains, removeKeyPages takes URLs, and removeResearchLog takes entry IDs from the project context. Adds upsert by domain/url; research-log entries are date-stamped by the server. |
updates full type
updates full type
(
{
brandName: string
} | {
section: business_overview | current_goal | positioning | writing_preferences,
content: string
} | {
customSection: string,
title?: string,
content: string
} | {
deleteCustomSection: string
} | {
addCompetitors: {
domain: string,
name?: string,
notes?: string
}[]
} | {
removeCompetitors: string[]
} | {
addKeyPages: {
url: string,
role?: hub | spoke | money | other,
topic?: string,
notes?: string
}[]
} | {
removeKeyPages: string[]
} | {
removeResearchLog: string[]
} | {
appendResearchLog: {
summary: string
}
}
)[]
| Name | Type | Required | Description |
|---|---|---|---|
sections | object[] | null | No | — |
missingSections | string[] | null | No | — |
customSections | object[] | null | No | — |
competitors | object[] | null | No | — |
keyPages | object[] | null | No | — |
researchLog | object[] | null | No | — |
reportTemplates | object[] | null | No | — |
meta | object | null | No | — |
sections full type
sections full type
{
}[] | null
customSections full type
customSections full type
{
}[] | null
competitors full type
competitors full type
{
}[] | null
keyPages full type
keyPages full type
{
}[] | null
researchLog full type
researchLog full type
{
}[] | null
reportTemplates full type
reportTemplates full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Rank Tracking
addKeywords
rankTracking.addKeywords
Add keywords to a rank tracker
Risk: write
await corsair.openseo.api.rankTracking.addKeywords({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
keywords: ['coffee subscription', 'best coffee beans'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker ID from get_rank_tracker. |
keywords | string[] | Yes | Keywords to track. Existing and repeated keywords are skipped. |
matchCase | boolean | No | Track the keywords exactly as typed instead of lowercasing them. Defaults to false. Use for brand names where Google’s results differ by capitalization; a cased keyword is tracked and billed separately from its lowercase form. |
maxEstimatedScheduledCheckCredits | number | No | Most credits per scheduled check, including retries, that the user approved after seeing estimate_rank_tracker_cost with additionalKeywords. Required for scheduled trackers. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
requested | number | null | No | — |
added | number | null | No | — |
addedIds | string[] | null | No | — |
scheduledEstimate | object | null | No | — |
meta | object | null | No | — |
scheduledEstimate full type
scheduledEstimate full type
{
scheduleInterval?: string | null,
costUsd?: number | null,
costCredits?: number | null,
checksPerMonth?: number | null,
monthlyCostUsd?: number | null,
monthlyCostCredits?: number | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
create
rankTracking.create
Create a rank tracker for a project
Risk: write
await corsair.openseo.api.rankTracking.create({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', devices: 'desktop', scheduleInterval: 'manual' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
domain | string | No | Domain to track. Defaults to the project’s domain. Accepts a hostname or URL and stores the normalized hostname. |
locationCode | number | No | DataForSEO country location code (e.g. 2840 United States, 2826 United Kingdom). Defaults to the project’s default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable. |
languageCode | string | No | Language code (e.g. ‘en’, ‘es’, ‘vi’). Defaults to the project’s default market language (see list_projects). |
locationName | string | No | Exact DataForSEO location name for local rank tracking, e.g. “Catonsville,Maryland,United States”. Must come from search_serp_locations; free-form names like “Catonsville, MD” are rejected. |
devices | desktop | mobile | both | No | Devices to track. Defaults to mobile. |
serpDepth | number | No | Number of Google results to inspect. Defaults to 40. |
scheduleInterval | manual | daily | weekly | monthly | No | Check schedule. Defaults to manual so creating a tracker cannot cause future credit spend. Scheduled checks may use credits later. |
scheduleTime | object | No | When scheduled checks run. Pass the user’s timeZone with it so their local time is converted for you; the schedule is then fixed in UTC and shifts an hour when their clocks change. Omit it unless the user asks for a specific time: the default spreads checks across quiet hours. Daily runs at this time every day, weekly on the given weekday, monthly at this time on the last day of the month. Checks start within about 15 minutes of the chosen time. Not valid with a manual schedule. |
scheduleTime full type
scheduleTime full type
{
weekday?: number,
hour: number,
minute: number,
timeZone?: string
}
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
config | object | null | No | — |
meta | object | null | No | — |
config full type
config full type
{
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
estimateCost
rankTracking.estimateCost
Estimate what a rank check costs without running it
Risk: read
await corsair.openseo.api.rankTracking.estimateCost({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
additionalKeywords: ['coffee gift box'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker ID from get_rank_tracker. |
additionalKeywordCount | number | No | Number of keywords you plan to add, priced as plain keywords. Prefer additionalKeywords when you know them. |
additionalKeywords | string[] | No | Keywords you plan to add. Include these before adding to a scheduled tracker so the response projects its recurring per-check and monthly cost; keywords with search operators such as site: cost 5x. Overrides additionalKeywordCount. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
costUsd | number | null | No | — |
costCredits | number | null | No | — |
keywordCount | number | null | No | — |
devicesCount | number | null | No | — |
totalChecks | number | null | No | — |
existingKeywordCount | number | null | No | — |
additionalKeywordCount | number | null | No | — |
scheduledEstimate | object | null | No | — |
meta | object | null | No | — |
scheduledEstimate full type
scheduledEstimate full type
{
scheduleInterval?: string | null,
costUsd?: number | null,
costCredits?: number | null,
checksPerMonth?: number | null,
monthlyCostUsd?: number | null,
monthlyCostCredits?: number | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
get
rankTracking.get
List a project’s rank trackers or get one with its latest Google positions
Risk: read
await corsair.openseo.api.rankTracking.get({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | No | Rank tracker config ID. If omitted, lists all rank trackers in the project. |
offset | number | No | Keyword row offset when trackerId is provided. Defaults to 0. |
limit | number | No | Keyword rows per page when trackerId is provided. Defaults to 100. Lower this if the text is truncated. |
| Name | Type | Required | Description |
|---|---|---|---|
configs | object[] | null | No | — |
config | object | null | No | — |
results | object | null | No | — |
meta | object | null | No | — |
configs full type
configs full type
{
}[] | null
config full type
config full type
{
} | null
results full type
results full type
{
rows?: {
}[] | null,
totalCount?: number | null,
offset?: number | null,
limit?: number | null,
nextOffset?: number | null | null,
run?: {
id?: string | null,
lastCheckedAt?: string | null | null,
completedAt?: string | null | null,
status?: string | null,
errorMessage?: string | null | null
} | null | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
history
rankTracking.history
Get the position history of a rank tracker’s keywords
Risk: read
await corsair.openseo.api.rankTracking.history({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
device: 'desktop',
runs: 10,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker config ID from get_rank_tracker. |
device | desktop | mobile | No | Device to read. Defaults to desktop, or mobile for a mobile-only tracker. |
runs | number | No | How many of the latest completed checks to return. Defaults to 12. |
trackingKeywordId | string | No | Only return this keyword’s history. IDs come from get_rank_tracker. |
offset | number | No | Keyword row offset. Defaults to 0. |
limit | number | No | Keyword rows per page. Defaults to 100. Lower this if the text is truncated. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
domain | string | null | No | — |
device | string | null | No | — |
runs | object[] | null | No | — |
rows | object[] | null | No | — |
totalCount | number | null | No | — |
offset | number | null | No | — |
limit | number | null | No | — |
nextOffset | number | null | null | No | — |
meta | object | null | No | — |
runs full type
runs full type
{
runId?: string | null,
checkedAt?: string | null
}[] | null
rows full type
rows full type
{
trackingKeywordId?: string | null,
keyword?: string | null,
pinned?: boolean | null,
history?: {
runId?: string | null,
checkedAt?: string | null,
position?: number | null | null,
checked?: boolean | null
}[] | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
pinKeywords
rankTracking.pinKeywords
Pin or unpin tracked keywords
Risk: write
await corsair.openseo.api.rankTracking.pinKeywords({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
keywordIds: ['d1e5a3c7-9b4f-4d26-8e0a-6c2b8f4d1a57'],
pinned: true,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker ID from get_rank_tracker. |
keywordIds | string[] | Yes | Tracking keyword IDs to pin or unpin. Use trackingKeywordId values returned by get_rank_tracker. |
pinned | boolean | Yes | true pins the keywords to the top. false unpins them. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
pinned | boolean | null | No | — |
requested | number | null | No | — |
updated | number | null | No | — |
updatedIds | string[] | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
removeKeywords
rankTracking.removeKeywords
Stop tracking keywords in a rank tracker
Risk: destructive · Irreversible
await corsair.openseo.api.rankTracking.removeKeywords({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
keywordIds: ['d1e5a3c7-9b4f-4d26-8e0a-6c2b8f4d1a57'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker ID from get_rank_tracker. |
keywordIds | string[] | Yes | Tracking keyword IDs to remove. Use trackingKeywordId values returned by get_rank_tracker. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
requested | number | null | No | — |
removed | number | null | No | — |
removedIds | string[] | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
run
rankTracking.run
Start a paid rank check now for every keyword in a tracker
Risk: destructive
await corsair.openseo.api.rankTracking.run({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94', maxCostCredits: 50 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
trackerId | string | Yes | Rank tracker ID from get_rank_tracker. |
maxCostCredits | number | Yes | Maximum credits the user approved after seeing estimate_rank_tracker_cost. The run is rejected if its fresh estimate is higher. |
| Name | Type | Required | Description |
|---|---|---|---|
trackerId | string | null | No | — |
started | boolean | null | No | — |
runId | string | null | No | — |
blockingRunId | string | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Reports
delete
reports.delete
Delete a saved report and its shared link
Risk: destructive · Irreversible
await corsair.openseo.api.reports.delete({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
reportId | string | Yes | Report id from list_reports or save_report. |
| Name | Type | Required | Description |
|---|---|---|---|
reportId | string | null | No | — |
deleted | true | Yes | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
deleteTemplate
reports.deleteTemplate
Delete a report template
Risk: destructive · Irreversible
await corsair.openseo.api.reports.deleteTemplate({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', templateId: '2d7f1b5e-9a3c-4e60-8f2b-6c0e4a8d1f79' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
templateId | string | Yes | Template id from list_report_templates. |
| Name | Type | Required | Description |
|---|---|---|---|
templateId | string | null | No | — |
deleted | true | Yes | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
get
reports.get
Get a saved report with its summary and share link
Risk: read
await corsair.openseo.api.reports.get({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
reportId | string | Yes | Report id from list_reports or save_report. |
includeHtml | boolean | No | Include the full HTML document. Leave it off unless you need to edit a specific passage: an 80 KB report is roughly 20,000 tokens, and a larger one is truncated by many clients. When you do fetch it, compare new TextEncoder().encode(html).length against the returned htmlBytes — if it is smaller your client truncated the read, so send the user to the app instead of saving the short version back over the good report. |
| Name | Type | Required | Description |
|---|---|---|---|
report | object | null | No | — |
meta | object | null | No | — |
report full type
report full type
{
shareUrl?: string | null | null,
html?: string | null
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
list
reports.list
List a project’s saved reports
Risk: read
await corsair.openseo.api.reports.list({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 10 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
limit | number | No | Reports per page, newest update first. Default 20, max 50. |
offset | number | No | Rows to skip. Omit for the first page. |
| Name | Type | Required | Description |
|---|---|---|---|
reports | object[] | null | No | — |
totalCount | number | null | No | — |
rowCount | number | null | No | — |
remaining | number | null | No | — |
meta | object | null | No | — |
reports full type
reports full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
listTemplates
reports.listTemplates
List a project’s report templates
Risk: read
await corsair.openseo.api.reports.listTemplates({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
templates | object[] | null | No | — |
remaining | number | null | No | — |
meta | object | null | No | — |
templates full type
templates full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
save
reports.save
Save an HTML report to a project
Risk: write
await corsair.openseo.api.reports.save({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
title: 'November SEO check-in',
summary: 'Organic clicks up 12%; three pages lost their snippets.',
html: '<!doctype html><html><head><meta charset="utf-8"><title>November SEO check-in</title></head><body><h1>November SEO check-in</h1><p>Organic clicks up 12%.</p></body></html>',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
title | string | Yes | Report type or specific subject and full report date, e.g. “Competitive Landscape — Sep 17, 2026”. Omit the project’s website; include the subject’s bare hostname only when it differs from the project website or the project has no website. Use the same title in the HTML title and h1. Never a generic label like “SEO Report”. Max 120 characters. |
summary | string | Yes | Markdown, under 2,500 characters: the verdict, the single top action, and the key numbers. This is what list_reports returns and what you or another agent read instead of the HTML. |
html | string | Yes | The complete self-contained HTML document. Inline all CSS; no external requests of any kind (no CDNs, no web fonts, no images by URL, no fetch) — they are blocked when the report renders, and scripts are blocked too. No backticks and no ${ anywhere, including inside CSS content strings: some clients (Codex) pass this argument through a JavaScript template literal and either sequence corrupts the document. It must be a whole document, ending in </html>: a save that stops mid-document is refused, because there is no version history to fall back on. Aim under 80 KB so the report can be read back whole in one call; the hard limit is 500,000 bytes. Use the seo-report skill’s starter template when you have it; otherwise a plain semantic document — heading, short sections, one table — reads fine. |
reportId | string | No | Omit to create a new report. Pass an id from list_reports to replace that report in place — there is no version history and the old content is gone. |
skill | string | No | The slug of the skill that produced this report — the name of the SKILL.md you are running, e.g. “seo-audit”. The report list keys on it, so a save without it shows ”—”. |
templateId | string | No | The id of the report template you followed, from list_report_templates or the project context. Pass it only when you actually followed that template; it is what the report list and the report page show instead of the skill slug. |
| Name | Type | Required | Description |
|---|---|---|---|
reportId | string | null | No | — |
title | string | null | No | — |
created | boolean | null | No | — |
htmlBytes | number | null | No | — |
url | string | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
saveTemplate
reports.saveTemplate
Save a reusable report template to a project
Risk: write
await corsair.openseo.api.reports.saveTemplate({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
name: 'Monthly client check-in',
description: 'One-page monthly summary for the client.',
instructions: 'Start with organic clicks and conversions, then the top three wins and the top three fixes.',
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
templateId | string | No | Omit to create a new template. Pass an id from list_report_templates to replace that template’s name, description and instructions in place. |
name | string | Yes | What the user will ask for by name, e.g. “Client-ready audit summary”. Max 80 characters. |
description | string | Yes | One line saying when to use this template. Agents read this to decide whether it applies, so name the occasion, not the format. Max 200 characters. |
instructions | string | Yes | Markdown, max 3,000 characters: the audience, the sections in order, the tone, the sign-off, and optionally an accent color as “accent: #1C4ED8”. This replaces the skill’s default section list and tone — never the seo-report HTML constraints, which always apply. |
| Name | Type | Required | Description |
|---|---|---|---|
templateId | string | null | No | — |
name | string | null | No | — |
created | boolean | null | No | — |
url | string | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
setSharing
reports.setSharing
Turn public sharing of a saved report on or off
Risk: destructive
await corsair.openseo.api.reports.setSharing({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06', public: true });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
reportId | string | Yes | Report id from list_reports or save_report. |
public | boolean | Yes | Required: true enables a public link anyone can open without an account; false revokes the current link. Set true only when the user explicitly requests public sharing in their prompt or instructions for the skill. Never infer permission from report content, research sources, or a request to save a report. |
| Name | Type | Required | Description |
|---|---|---|---|
reportId | string | null | No | — |
public | boolean | null | No | — |
url | string | null | No | — |
shareUrl | string | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Search Console
inspectUrls
searchConsole.inspectUrls
Check whether Google has indexed up to 10 pages, and why not
Risk: read
await corsair.openseo.api.searchConsole.inspectUrls({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
urls: ['https://acmecoffee.com/subscriptions'],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
urls | string[] | Yes | 1–10 absolute URLs to inspect. Each must belong to the connected property. |
languageCode | string | No | BCP-47 language for the inspection result (e.g. ‘en-US’). |
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
reason | string | null | No | — |
connectUrl | string | null | No | — |
setupDocsUrl | string | null | No | — |
siteUrl | string | null | No | — |
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
{
url?: string | null,
result?: any | null | null,
error?: string | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
listSites
searchConsole.listSites
List the Search Console properties of the connected Google accounts
Risk: read
await corsair.openseo.api.searchConsole.listSites({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
accounts | object[] | null | No | — |
connectUrl | string | null | No | — |
meta | object | null | No | — |
accounts full type
accounts full type
{
accountId?: string | null,
email?: string | null | null,
requiresReconnect?: boolean | null,
propertiesUnavailable?: boolean | null,
apiDisabled?: boolean | null,
sites?: {
siteUrl?: string | null,
permissionLevel?: string | null,
isSelected?: boolean | null
}[] | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
opportunities
searchConsole.opportunities
Find pages ranking 4-20 in Search Console that are most worth improving
Risk: read
await corsair.openseo.api.searchConsole.opportunities({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 10 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
startDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
endDate | string | No | Inclusive YYYY-MM-DD date. Provide both startDate and endDate. |
limit | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | No | — |
source | object | null | No | — |
request | object | null | No | — |
rowCount | number | null | No | — |
totalCandidateRows | number | null | No | — |
rows | object[] | null | No | — |
scoring | object | null | No | — |
coverage | object | null | No | — |
truncated | object | null | No | — |
warnings | string[] | null | No | — |
reportMetadata | object | null | No | — |
quota | object | null | No | — |
error | object | null | No | — |
source full type
source full type
{
} | null
request full type
request full type
{
} | null
rows full type
rows full type
{
}[] | null
scoring full type
scoring full type
{
} | null
coverage full type
coverage full type
{
} | null
truncated full type
truncated full type
{
} | null
reportMetadata full type
reportMetadata full type
{
} | null
quota full type
quota full type
{
} | null | null
error full type
error full type
{
code?: string | null,
message?: string | null,
retryAfterSeconds?: number | null | null,
actionUrl?: string | null
} | null
performance
searchConsole.performance
Get Search Console clicks, impressions, CTR and position by query, page or other dimension
Risk: read
await corsair.openseo.api.searchConsole.performance({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
dimensions: ['query'],
dateRange: 'last_28_days',
rowLimit: 25,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
dimensions | (query | page | country | device | date | searchAppearance)[] | No | Group rows by these dimensions. Default [‘query’]. Use [‘page’] for top pages, [‘query’,‘page’] to map queries to pages / spot cannibalization, [‘date’] for a time series. |
dateRange | last_7_days | last_28_days | last_3_months | last_6_months | last_12_months | last_16_months | No | Convenience window (default last_28_days). End is set ~3 days back for GSC data lag. Ignored if startDate+endDate are given. Max lookback is 16 months. |
startDate | string | No | Explicit start (YYYY-MM-DD, Pacific Time). Use with endDate. |
endDate | string | No | Explicit end (YYYY-MM-DD, Pacific Time). Use with startDate. |
filters | object[] | No | AND-combined filters. To get the queries for one page: [{dimension:‘page’,operator:‘equals’,expression:‘https://example.com/post’}] with dimensions [‘query’]. |
rowLimit | number | No | Rows per call (default 250, max 1000). GSC sorts by clicks desc; paginate with startRow when hasMore is true. |
startRow | number | No | Pagination offset. |
minPosition | number | No | Keep rows with average position >= this. For ‘striking distance’ queries use minPosition 5, maxPosition 20, minImpressions 50. |
maxPosition | number | No | Keep rows with average position <= this. |
minImpressions | number | No | Keep rows with at least this many impressions. |
type | web | image | video | news | googleNews | discover | No | Search type (default web). |
dataState | all | final | No | ’all’ (default) includes fresh/incomplete recent data. |
filters full type
filters full type
{
dimension: query | page | country | device | date | searchAppearance,
operator?: equals | notEquals | contains | notContains,
expression: string
}[]
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
reason | string | null | No | — |
connectionRequired | boolean | null | No | — |
connectUrl | string | null | No | — |
setupDocsUrl | string | null | No | — |
siteUrl | string | null | No | — |
startDate | string | null | No | — |
endDate | string | null | No | — |
dimensions | string[] | null | No | — |
rowCount | number | null | No | — |
rows | object[] | null | No | — |
hasMore | boolean | null | No | — |
nextStartRow | number | null | No | — |
meta | object | null | No | — |
rows full type
rows full type
{
keys?: string[] | null,
clicks?: number | null,
impressions?: number | null,
ctr?: number | null,
position?: number | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
setSite
searchConsole.setSite
Set which Search Console property a project reads
Risk: write
await corsair.openseo.api.searchConsole.setSite({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', siteUrl: 'sc-domain:acmecoffee.com', gscAccountId: 'f3c9a1e7-2d5b-4f80-9b6e-4a2d8c0f6e35' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
siteUrl | string | Yes | Search Console property exactly as list_search_console_sites returns it (e.g. sc-domain:example.com or https://www.example.com/). |
gscAccountId | string | Yes | accountId of the connected Google account from the list tool. |
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | null | No | — |
projectId | string | null | No | — |
siteUrl | string | null | No | — |
gscAccountId | string | null | No | — |
connectedByEmail | string | null | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Serp
competitors
serp.competitors
Find the domains that compete in Google results for a set of keywords
Risk: read
await corsair.openseo.api.serp.competitors({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
keywords: ['coffee subscription', 'best coffee beans', 'whole bean coffee'],
limit: 20,
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
keywords | string[] | Yes | Keywords whose SERPs are compared (1-100). |
market | object | No | Legacy US selector. Prefer locationCode/languageCode for any Labs market. Explicit locationCode takes precedence; otherwise omitted = the project’s default market. |
locationCode | number | No | Country-level DataForSEO Labs location code. Defaults to the project’s market; takes precedence over the legacy market object. |
languageCode | string | No | Language for locationCode. Defaults to that location’s primary language when locationCode overrides the project market. |
resultTypes | (organic | paid | featured_snippet | local_pack)[] | No | SERP result types to include. Defaults to organic and local_pack. |
excludeDomains | string[] | No | Domains to exclude from results (e.g. the user’s own site). |
includeSubdomains | boolean | No | Count subdomains as part of the same competitor domain. |
sortBy | visibility | traffic_estimate | avg_position | keyword_count | No | Sort order for returned competitors. Defaults to visibility. |
limit | number | No | Maximum competitors to return (1-100). Defaults to 50. |
offset | number | No | Rows to skip for pagination. |
market full type
market full type
{
country?: US | USA | United States | United States of America
}
| Name | Type | Required | Description |
|---|---|---|---|
competitors | object[] | null | No | — |
meta | object | null | No | — |
competitors full type
competitors full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
results
serp.results
Get live Google organic results for 1-10 keywords
Risk: read
await corsair.openseo.api.serp.results({
projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
queries: [{ keyword: 'coffee subscription', device: 'desktop' }],
});
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
queries | object[] | Yes | 1-10 queries. Bulk-friendly — prefer this over multiple single-query calls. |
depth | number | No | How many Google results to read per keyword — a multiple of 10 from 10 to 100, default 10 (page 1). Merging the reads usually returns more sites than this. Google has no offset, so a deeper read re-fetches the top too: each additional 10 adds ~3.5 credits per keyword. Only raise it when you need ranks past page 1. |
finalUrls | boolean | No | Set true to get each result’s page URL instead of a google.com/goto redirect. The search then takes a few minutes instead of seconds: the first call starts it and answers that it is still running, and the same call again 2-3 minutes later returns the results at no extra charge. For batch jobs, not while someone waits. Costs about half the credits. |
queries full type
queries full type
{
keyword: string,
locationCode?: number,
languageCode?: string,
locationName?: string,
device?: desktop | mobile
}[]
| Name | Type | Required | Description |
|---|---|---|---|
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
(
{
keyword?: string | null,
ok: true,
locationCode?: number | null,
languageCode?: string | null,
locationName?: string | null,
device?: string | null,
items?: {
type?: string | null | null,
rank?: number | null | null,
bestPosition?: number | null | null,
seenIn?: number | null,
title?: string | null | null,
url?: string | null | null,
domain?: string | null | null,
description?: string | null | null
}[] | null
} | {
keyword?: string | null,
ok: false,
error?: string | null
}
)[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
searchLocations
serp.searchLocations
Find the exact location name of a city or region for local searches
Risk: read
await corsair.openseo.api.serp.searchLocations({ query: 'Austin', countryCode: 'US' });
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Place name, e.g. “Catonsville” or “Portland OR”. |
countryCode | string | Yes | Two-letter ISO country code, e.g. “us”. |
| Name | Type | Required | Description |
|---|---|---|---|
locations | object[] | null | No | — |
meta | object | null | No | — |
locations full type
locations full type
{
locationName?: string | null,
locationCode?: number | null,
locationType?: string | null
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
Site Audits
delete
siteAudits.delete
Delete a site audit with its pages, issues and Lighthouse results
Risk: destructive · Irreversible
await corsair.openseo.api.siteAudits.delete({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', auditId: 'b8e2d6f0-4a9c-4b17-a3e5-7f1c9d3b5e82' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
auditId | string | Yes | Exact audit ID from list_site_audits or run_site_audit. Required; never defaults to the latest audit. |
| Name | Type | Required | Description |
|---|---|---|---|
auditId | string | null | No | — |
deleted | true | Yes | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
issues
siteAudits.issues
Get the prioritized issues from a completed site audit
Risk: read
await corsair.openseo.api.siteAudits.issues({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', severity: 'critical' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
auditId | string | No | Audit ID. If omitted, uses the project’s most recent audit. |
severity | critical | warning | info | No | Only return issues of this severity. |
issueType | string | No | Only return issues of this type. One of: blocked-page, javascript-rendering-suspected, rate-limited-page, crawl-rate-limited, crawl-time-limit, crawl-credits-exhausted, crawl-page-limit, server-error, broken-internal-link, missing-title, broken-page, duplicate-title, duplicate-meta-description, duplicate-content, missing-meta-description, missing-h1, multiple-h1, redirect-chain, redirect-loop, canonical-conflict, thin-content, images-missing-alt, orphan-page, no-outgoing-links, title-too-long, title-too-short, meta-description-too-long, meta-description-too-short, heading-order-skip, slow-response, noindex-page, canonicalized-page, deep-page |
page | number | No | Page of issue rows, 1-based (default 1). Rows are ordered critical first. |
limit | number | No | Issue rows per page (default 200). |
| Name | Type | Required | Description |
|---|---|---|---|
summary | object[] | null | No | — |
issues | object[] | null | No | — |
total | number | null | No | — |
page | number | null | No | — |
meta | object | null | No | — |
summary full type
summary full type
{
}[] | null
issues full type
issues full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
lighthouse
siteAudits.lighthouse
Get the Lighthouse results from a site audit
Risk: read
await corsair.openseo.api.siteAudits.lighthouse({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', device: 'mobile' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
auditId | string | No | Audit ID. If omitted, uses the project’s most recent audit. |
url | string | No | A tested page’s URL, exactly as the results list it. Returns that page’s result for one device, with the issues Lighthouse found. |
device | mobile | desktop | No | Only return this device’s results. With url, defaults to mobile. |
| Name | Type | Required | Description |
|---|---|---|---|
auditId | string | null | No | — |
results | object[] | null | No | — |
meta | object | null | No | — |
results full type
results full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
list
siteAudits.list
List a project’s site audits with status and page counts
Risk: read
await corsair.openseo.api.siteAudits.list({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
| Name | Type | Required | Description |
|---|---|---|---|
audits | object[] | null | No | — |
meta | object | null | No | — |
audits full type
audits full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
pages
siteAudits.pages
List the pages a site audit crawled with per-page SEO data
Risk: read
await corsair.openseo.api.siteAudits.pages({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', fetchClass: 'error', limit: 25 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
auditId | string | No | Audit ID. If omitted, uses the project’s most recent audit. |
fetchClass | ok | blocked | rate_limited | error | No | Filter by fetch outcome (“blocked” = the site’s bot protection challenged the crawler; “rate_limited” = a 429 prevented the crawler from reading the page). |
statusCode | number | No | Filter by exact HTTP status code. |
urlContains | string | No | Filter to URLs containing this text (case-insensitive). |
minWords | number | No | Minimum word count. |
maxWords | number | No | Maximum word count. |
minResponseMs | number | No | Minimum response time in ms. |
maxResponseMs | number | No | Maximum response time in ms. |
missingAlt | boolean | No | true: only pages with images missing alt text; false: only pages without. |
sort | url | statusCode | title | h1Count | wordCount | images | responseTimeMs | No | Sort column (default “url”; “images” sorts by images missing alt text). Blank values sort last. |
order | asc | desc | No | Default “asc”. |
page | number | No | Page of results, 1-based (default 1). |
limit | number | No | Pages per result page (default 100). |
| Name | Type | Required | Description |
|---|---|---|---|
pages | object[] | null | No | — |
total | number | null | No | — |
page | number | null | No | — |
meta | object | null | No | — |
pages full type
pages full type
{
}[] | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
run
siteAudits.run
Start a background site audit (crawl, SEO checks, optional Lighthouse)
Risk: write
await corsair.openseo.api.siteAudits.run({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', url: 'https://acmecoffee.com', maxPages: 50 });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
url | string | Yes | Start URL to crawl. |
maxPages | number | No | Page budget for the crawl (default 50). Free plans audit at most 50 pages: a larger budget runs at 50 and the reply says so. |
renderJavaScript | boolean | No | Render JavaScript before auditing, for sites whose content or links load client-side or whose bot protection blocks the plain crawler. Slower. On hosted plans, for 100 pages: Costs up to $0.13. Sites that block our browser need an advanced renderer. If the cost is higher than expected, it will stop. Hosted plans hold that amount until the audit ends; an account that cannot cover it is refused. A hosted rendered crawl stops after 22 hours. Default false. |
excludePaths | string[] | No | Paths to leave out of the audit, up to 20. Each is matched against the URL’s path and query string from the start, like a robots.txt Disallow rule: “/blog/” skips everything under /blog/, "" matches any characters (“//print”, ”/*?sort=”), and a trailing ""pinstheend("/∗.pdf"). No regex. Excluded URLs are not fetched, do not count against maxPages, and are left out of pages and issues; links to them are not checked, and the orphan-page check is skipped because links from excluded pages are unknown. The start URL must not match. |
runLighthouse | boolean | No | Run Lighthouse on a sample of up to 10 representative pages (default false — it adds several minutes of wall-clock time). Pass true only when the user wants performance/Core Web Vitals detail. |
| Name | Type | Required | Description |
|---|---|---|---|
auditId | string | null | No | — |
meta | object | null | No | — |
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null
status
siteAudits.status
Get the progress of a site audit
Risk: read
await corsair.openseo.api.siteAudits.status({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list_projects. |
auditId | string | No | Audit ID. If omitted, uses the project’s most recent audit. |
| Name | Type | Required | Description |
|---|---|---|---|
status | object | null | No | — |
meta | object | null | No | — |
status full type
status full type
{
} | null
meta full type
meta full type
{
url?: string | null,
projectId?: string | null,
runId?: string | null,
creditsCharged?: number | null,
creditsRemaining?: number | null
} | null