> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSEO API reference

> API reference for the OpenSEO plugin in Corsair: every `openseo.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Account

### whoami

`account.whoami`

Get the connected OpenSEO account, token scopes and remaining credits

**Risk:** `read`

```ts theme={null}
await corsair.openseo.api.account.whoami({});
```

**Input:** *empty object*

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.completeResearchSetup({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   keywords?: string[] | null,
>   status?: string | null,
>   review?: {
>   } | null | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.estimateCost({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', scheduleInterval: 'weekly' });
```

**Input**

| 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 | — |

> [accordion] patch full type
>
> ```ts theme={null}
> {
>   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[]
> }
> ```

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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',
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] results full type
>
> ```ts theme={null}
> (
>   {
>     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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.export({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', format: 'csv', includeHistory: true });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   url?: string | null,
>   expiresAt?: string | null,
>   format?: string | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.generatePrompts({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	topic: 'Coffee subscriptions',
	locationCode: 2840,
	languageCode: 'en',
});
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   topic?: string | null,
>   prompts?: string[] | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getAnswer({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', observationId: 'e4b8c2a6-1d3f-4a97-8c5e-2f6a0b9d7e13' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | — |
| `observationId` | `string` | Yes | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getResults({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', competitorGap: true, limit: 20 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getRun({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', runId: 'c7a3d9e1-5b2f-4c86-a0d4-9e1f3b7c5a28' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | — |
| `runId` | `string` | Yes | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getSources({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	groupBy: 'domain',
	ownership: 'competitor',
	limit: 20,
});
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getTracker({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.getTrend({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', days: 28 });
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.researchPrompts({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', keyword: 'coffee subscription' });
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.runCheck({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', maxCostUsd: 0.5 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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' }],
});
```

**Input**

| 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 | — |

> [accordion] prompts full type
>
> ```ts theme={null}
> {
>   id?: string,
>   text: string,
>   topic?: string,
>   paused?: boolean
> }[]
> ```

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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',
	},
});
```

**Input**

| 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. |

> [accordion] scheduleTime full type
>
> ```ts theme={null}
> {
>   weekday?: number,
>   hour: number,
>   minute: number,
>   timeZone?: string
> }
> ```

**Output**

| 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 | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.aiVisibility.updateResearchKeywords({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	add: ['coffee subscription'],
	remove: ['coffee pods'],
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `keywords` | `string[] \| null` | No | — |
| `trackedTopics` | `string[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.backlinks.list({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	target: 'bluebottlecoffee.com',
	pageSize: 50,
	sortField: 'rank',
	sortOrder: 'desc',
});
```

**Input**

| 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](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. |

> [accordion] filters full type
>
> ```ts theme={null}
> {
>   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
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `target` | `string \| null` | No | — |
| `scope` | `string \| null` | No | — |
| `backlinks` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] backlinks full type
>
> ```ts theme={null}
> {
>   rows?: {
>   }[] | null,
>   totalCount?: number | null | null,
>   hasMore?: boolean | null,
>   page?: number | null,
>   pageSize?: number | null,
>   fetchedAt?: string | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.backlinks.overview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', target: 'bluebottlecoffee.com' });
```

**Input**

| 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](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. |

**Output**

| 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 | — |

> [accordion] overview full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] referringDomains full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.domains.keywords({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', domain: 'bluebottlecoffee.com' });
```

**Input**

| 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). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `keywords` | `object[] \| null` | No | — |
| `target` | `string \| null` | No | — |
| `scope` | `string \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] keywords full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.domains.overview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', domain: 'bluebottlecoffee.com' });
```

**Input**

| 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). |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.domains.rankedKeywords({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	target: 'bluebottlecoffee.com',
	maxRank: 10,
	limit: 50,
});
```

**Input**

| 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. |

> [accordion] market full type
>
> ```ts theme={null}
> {
>   country?: US | USA | United States | United States of America
> }
> ```

**Output**

| 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 | — |

> [accordion] keywords full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.audienceBreakdown({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'device' });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.ecommercePerformance({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'item', limit: 20 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.keyEvents({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'event', comparePreviousPeriod: true });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.listProperties({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ok` | `boolean \| null` | No | — |
| `accounts` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] accounts full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.measurementHealth({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] summary full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] webStreams full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] otherStreams full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] keyEvents full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] customDefinitions full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.organicLandingPages({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 20 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.organicOverview({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', trend: 'weekly' });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] current full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] previous full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] trend full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.pagePerformance({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', channel: 'organic_search', limit: 20 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.setProperty({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', propertyId: 'properties/412345678', ga4AccountId: 'f3c9a1e7-2d5b-4f80-9b6e-4a2d8c0f6e35' });
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.siteSearch({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 20 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.googleAnalytics.trafficAcquisition({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', breakdown: 'channel_group' });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] pageInfo full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] comparison full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] ecommerceActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] siteSearchActivity full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] diagnostics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] diagnosticCoverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.indexNow.submitUrls({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	urls: ['https://acmecoffee.com/blog/cold-brew-guide'],
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `key` | `string \| null` | No | — |
| `keyCreated` | `boolean \| null` | No | — |
| `hosts` | `object[] \| null` | No | — |
| `skipped` | `string[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] hosts full type
>
> ```ts theme={null}
> {
>   host?: string | null,
>   urlCount?: number | null,
>   status?: string | null,
>   message?: string | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.keywords.listSaved({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 50 });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `rows` | `object[] \| null` | No | — |
| `totalCount` | `number \| null` | No | — |
| `tags` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] rows full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] tags full type
>
> ```ts theme={null}
> {
>   name?: string | null,
>   keywordCount?: number | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.keywords.metrics({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	keywords: ['coffee subscription', 'whole bean coffee'],
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `keywords` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] keywords full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.keywords.removeSaved({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	savedKeywordIds: ['b2f6e0d4-8a1c-4f3e-9d27-5c4a1e8b3f60'],
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string \| null` | No | — |
| `requested` | `number \| null` | No | — |
| `deletedCount` | `number \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.keywords.research({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	seeds: [{ seed: 'coffee subscription' }],
	resultLimit: 150,
});
```

**Input**

| 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. |

> [accordion] seeds full type
>
> ```ts theme={null}
> {
>   seed: string,
>   locationCode?: number,
>   languageCode?: string,
>   locationName?: string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> (
>   {
>     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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.keywords.save({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	keywords: ['coffee subscription', 'best coffee beans'],
	tags: ['subscriptions'],
});
```

**Input**

| 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). |

> [accordion] metrics full type
>
> ```ts theme={null}
> {
>   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
>   }[]
> }[]
> ```

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.keywords.suggestions({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `suggestions` | `object[] \| null` | No | — |
| `searchConsoleConnected` | `boolean \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] suggestions full type
>
> ```ts theme={null}
> {
>   keyword?: string | null,
>   reason?: string | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.local.businessProfile({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	businessName: 'Houndstooth Coffee',
	near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
```

**Input**

| 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). |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   radiusKm?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `profile` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] profile full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.local.businessQuestions({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	businessName: 'Houndstooth Coffee',
	near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
```

**Input**

| 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). |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   radiusKm: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `questions` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] questions full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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',
});
```

**Input**

| 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. |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   radiusKm?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `string \| null` | No | — |
| `taskId` | `string \| null` | No | — |
| `reviews` | `object[] \| null` | No | — |
| `totals` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] reviews full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] totals full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.local.businessUpdates({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	businessName: 'Houndstooth Coffee',
	near: { latitude: 30.2672, longitude: -97.7431, radiusKm: 10 },
});
```

**Input**

| 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. |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   radiusKm?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `string \| null` | No | — |
| `taskId` | `string \| null` | No | — |
| `updates` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] updates full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.local.listCategories({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', query: 'coffee', limit: 10 });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `categories` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] categories full type
>
> ```ts theme={null}
> {
>   category?: string | null,
>   businessCount?: number | null | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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,
});
```

**Input**

| 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). |

> [accordion] target full type
>
> ```ts theme={null}
> {
>   cid?: string,
>   placeId?: string,
>   name?: string
> }
> ```

> [accordion] center full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number
> }
> ```

**Output**

| 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 | — |

> [accordion] grid full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] summary full type
>
> ```ts theme={null}
> {
>   pointsSearched?: number | null,
>   pointsFound?: number | null,
>   averageRank?: number | null | null,
>   top3Count?: number | null,
>   top10Count?: number | null
> } | null
> ```

> [accordion] matchedBusiness full type
>
> ```ts theme={null}
> {
>   title?: string | null | null,
>   cid?: string | null | null,
>   placeId?: string | null | null
> } | null | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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,
});
```

**Input**

| 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. |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   radiusKm: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `businesses` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] businesses full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.local.serpResults({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	keyword: 'coffee shop',
	near: { latitude: 30.2672, longitude: -97.7431 },
	searchType: 'maps',
});
```

**Input**

| 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). |

> [accordion] near full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number,
>   zoom?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.projects.create({
	name: 'Acme Coffee',
	domain: 'acmecoffee.com',
	locationCode: 2840,
	languageCode: 'en',
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   domain?: string | null | null,
>   locationCode?: number | null,
>   languageCode?: string | null,
>   url?: string | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.projects.getContext({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| 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 | — |

> [accordion] sections full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] customSections full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] competitors full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] keyPages full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] researchLog full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] reportTemplates full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.projects.list({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `projects` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   domain?: string | null | null,
>   locationCode?: number | null,
>   languageCode?: string | null,
>   url?: string | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.projects.researchWebsite({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', website: 'https://acmecoffee.com' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | — |
| `website` | `string` | Yes | — |

**Output**

| 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 | — |

> [accordion] competitors full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] suggestedTopics full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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' }],
});
```

**Input**

| 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 | — |

> [accordion] competitors full type
>
> ```ts theme={null}
> {
>   name: string,
>   domain: string,
>   notes?: string
> }[]
> ```

> [accordion] suggestedTopics full type
>
> ```ts theme={null}
> {
>   name: string,
>   prompts: string[]
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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.' }],
});
```

**Input**

| 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. |

> [accordion] updates full type
>
> ```ts theme={null}
> (
>   {
>     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
>     }
>   }
> )[]
> ```

**Output**

| 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 | — |

> [accordion] sections full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] customSections full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] competitors full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] keyPages full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] researchLog full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] reportTemplates full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.addKeywords({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
	keywords: ['coffee subscription', 'best coffee beans'],
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] scheduledEstimate full type
>
> ```ts theme={null}
> {
>   scheduleInterval?: string | null,
>   costUsd?: number | null,
>   costCredits?: number | null,
>   checksPerMonth?: number | null,
>   monthlyCostUsd?: number | null,
>   monthlyCostCredits?: number | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.create({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', devices: 'desktop', scheduleInterval: 'manual' });
```

**Input**

| 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. |

> [accordion] scheduleTime full type
>
> ```ts theme={null}
> {
>   weekday?: number,
>   hour: number,
>   minute: number,
>   timeZone?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `trackerId` | `string \| null` | No | — |
| `config` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] config full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.estimateCost({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
	additionalKeywords: ['coffee gift box'],
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] scheduledEstimate full type
>
> ```ts theme={null}
> {
>   scheduleInterval?: string | null,
>   costUsd?: number | null,
>   costCredits?: number | null,
>   checksPerMonth?: number | null,
>   monthlyCostUsd?: number | null,
>   monthlyCostCredits?: number | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.get({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `configs` | `object[] \| null` | No | — |
| `config` | `object \| null` | No | — |
| `results` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] configs full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] config full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.history({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
	device: 'desktop',
	runs: 10,
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] runs full type
>
> ```ts theme={null}
> {
>   runId?: string | null,
>   checkedAt?: string | null
> }[] | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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,
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.rankTracking.removeKeywords({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94',
	keywordIds: ['d1e5a3c7-9b4f-4d26-8e0a-6c2b8f4d1a57'],
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `trackerId` | `string \| null` | No | — |
| `requested` | `number \| null` | No | — |
| `removed` | `number \| null` | No | — |
| `removedIds` | `string[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.rankTracking.run({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', trackerId: 'a9d2f4b6-7c1e-4e38-b5a0-3d8c6f2e1b94', maxCostCredits: 50 });
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.reports.delete({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `reportId` | `string \| null` | No | — |
| `deleted` | `true` | Yes | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.reports.deleteTemplate({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', templateId: '2d7f1b5e-9a3c-4e60-8f2b-6c0e4a8d1f79' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string \| null` | No | — |
| `deleted` | `true` | Yes | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.reports.get({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `report` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] report full type
>
> ```ts theme={null}
> {
>   shareUrl?: string | null | null,
>   html?: string | null
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.reports.list({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 10 });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `reports` | `object[] \| null` | No | — |
| `totalCount` | `number \| null` | No | — |
| `rowCount` | `number \| null` | No | — |
| `remaining` | `number \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] reports full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.reports.listTemplates({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `templates` | `object[] \| null` | No | — |
| `remaining` | `number \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] templates full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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>',
});
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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.',
});
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string \| null` | No | — |
| `name` | `string \| null` | No | — |
| `created` | `boolean \| null` | No | — |
| `url` | `string \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.reports.setSharing({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', reportId: '9c4e8a2d-6f1b-4d53-b7e9-1a5c3f8d2b06', public: true });
```

**Input**

| 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. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.searchConsole.inspectUrls({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	urls: ['https://acmecoffee.com/subscriptions'],
});
```

**Input**

| 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'). |

**Output**

| 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 | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   url?: string | null,
>   result?: any | null | null,
>   error?: string | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.searchConsole.listSites({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ok` | `boolean \| null` | No | — |
| `accounts` | `object[] \| null` | No | — |
| `connectUrl` | `string \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] accounts full type
>
> ```ts theme={null}
> {
>   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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.searchConsole.opportunities({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', limit: 10 });
```

**Input**

| 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 | — |

**Output**

| 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 | — |

> [accordion] source full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] request full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] rows full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] scoring full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] coverage full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] truncated full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] reportMetadata full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] error full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.searchConsole.performance({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	dimensions: ['query'],
	dateRange: 'last_28_days',
	rowLimit: 25,
});
```

**Input**

| 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](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. |

> [accordion] filters full type
>
> ```ts theme={null}
> {
>   dimension: query | page | country | device | date | searchAppearance,
>   operator?: equals | notEquals | contains | notContains,
>   expression: string
> }[]
> ```

**Output**

| 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 | — |

> [accordion] rows full type
>
> ```ts theme={null}
> {
>   keys?: string[] | null,
>   clicks?: number | null,
>   impressions?: number | null,
>   ctr?: number | null,
>   position?: number | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.searchConsole.setSite({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', siteUrl: 'sc-domain:acmecoffee.com', gscAccountId: 'f3c9a1e7-2d5b-4f80-9b6e-4a2d8c0f6e35' });
```

**Input**

| 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/](https://www.example.com/)). |
| `gscAccountId` | `string` | Yes | accountId of the connected Google account from the list tool. |

**Output**

| 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 | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.serp.competitors({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	keywords: ['coffee subscription', 'best coffee beans', 'whole bean coffee'],
	limit: 20,
});
```

**Input**

| 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. |

> [accordion] market full type
>
> ```ts theme={null}
> {
>   country?: US | USA | United States | United States of America
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `competitors` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] competitors full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.serp.results({
	projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31',
	queries: [{ keyword: 'coffee subscription', device: 'desktop' }],
});
```

**Input**

| 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. |

> [accordion] queries full type
>
> ```ts theme={null}
> {
>   keyword: string,
>   locationCode?: number,
>   languageCode?: string,
>   locationName?: string,
>   device?: desktop | mobile
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> (
>   {
>     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
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.serp.searchLocations({ query: 'Austin', countryCode: 'US' });
```

**Input**

| 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". |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `locations` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] locations full type
>
> ```ts theme={null}
> {
>   locationName?: string | null,
>   locationCode?: number | null,
>   locationType?: string | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
await corsair.openseo.api.siteAudits.delete({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', auditId: 'b8e2d6f0-4a9c-4b17-a3e5-7f1c9d3b5e82' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `auditId` | `string \| null` | No | — |
| `deleted` | `true` | Yes | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.issues({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', severity: 'critical' });
```

**Input**

| 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). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `summary` | `object[] \| null` | No | — |
| `issues` | `object[] \| null` | No | — |
| `total` | `number \| null` | No | — |
| `page` | `number \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] summary full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] issues full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.lighthouse({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', device: 'mobile' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `auditId` | `string \| null` | No | — |
| `results` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.list({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | `string` | Yes | Required. The OpenSEO project ID to scope this call to. Get one from list\_projects. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `audits` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] audits full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.pages({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', fetchClass: 'error', limit: 25 });
```

**Input**

| 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). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `pages` | `object[] \| null` | No | — |
| `total` | `number \| null` | No | — |
| `page` | `number \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] pages full type
>
> ```ts theme={null}
> {
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.run({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31', url: 'https://acmecoffee.com', maxPages: 50 });
```

**Input**

| 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 "$" pins the end ("/*.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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `auditId` | `string \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.openseo.api.siteAudits.status({ projectId: '6f1c2a9e-3b7d-4e58-9a14-2c8b5d7e0f31' });
```

**Input**

| 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. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `object \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] status full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   url?: string | null,
>   projectId?: string | null,
>   runId?: string | null,
>   creditsCharged?: number | null,
>   creditsRemaining?: number | null
> } | null
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.