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

# API

> API reference for Browser Use: every `browseruse.api.*` operation with input and output types.

Every `browseruse.api.*` operation is listed below with parameter shapes and return types from the plugin 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).

## Browsers

### create

`browsers.create`

POST /browsers — start a cloud browser; returns cdpUrl for Playwright/Puppeteer and a liveUrl

**Risk:** `write`

```ts theme={null}
await corsair.browseruse.api.browsers.create({ proxyCountryCode: 'us', timeout: 15 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `profileId` | `string` | No | — |
| `proxyCountryCode` | `ad \| ae \| af \| ag \| ai \| al \| am \| an \| ao \| aq \| ar \| as \| at \| au \| aw \| 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 \| co \| cr \| cs \| 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 \| 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 \| 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 \| uk \| us \| uy \| uz \| va \| vc \| ve \| vg \| vi \| vn \| vu \| wf \| ws \| xk \| ye \| yt \| za \| zm \| zw` | No | — |
| `timeout` | `number` | No | — |
| `browserScreenWidth` | `number` | No | — |
| `browserScreenHeight` | `number` | No | — |
| `allowResizing` | `boolean` | No | — |
| `pdfRendererEnabled` | `boolean` | No | — |
| `solveCaptchas` | `boolean` | No | — |
| `enableRecording` | `boolean` | No | — |
| `metadata` | `object` | No | — |
| `customProxy` | `object` | No | — |
| `extensionIds` | `string[]` | No | — |

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

> [accordion] customProxy full type
>
> ```ts theme={null}
> {
>   host: string,
>   port: number,
>   username?: string | null,
>   password?: string | null,
>   ignoreCertErrors?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `status` | `active \| stopped` | Yes | — |
| `liveUrl` | `string` | No | — |
| `cdpUrl` | `string` | No | — |
| `timeoutAt` | `string` | Yes | — |
| `startedAt` | `string` | Yes | — |
| `finishedAt` | `string` | No | — |
| `proxyUsedMb` | `string` | No | — |
| `proxyCost` | `string` | No | — |
| `browserCost` | `string` | No | — |
| `agentSessionId` | `string` | No | — |
| `recordingUrl` | `string` | No | — |
| `recordingAvailable` | `boolean` | No | — |
| `metadata` | `object` | No | — |
| `extensions` | `object[]` | No | — |

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

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id: string,
>   runtimeId: string,
>   version: string
> }[]
> ```

***

### get

`browsers.get`

GET /browsers/\{id} — browser status, URLs, cost, recording

**Risk:** `read`

```ts theme={null}
await corsair.browseruse.api.browsers.get({ id: '<browser-id>' });
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `status` | `active \| stopped` | Yes | — |
| `liveUrl` | `string` | No | — |
| `cdpUrl` | `string` | No | — |
| `timeoutAt` | `string` | Yes | — |
| `startedAt` | `string` | Yes | — |
| `finishedAt` | `string` | No | — |
| `proxyUsedMb` | `string` | No | — |
| `proxyCost` | `string` | No | — |
| `browserCost` | `string` | No | — |
| `agentSessionId` | `string` | No | — |
| `recordingUrl` | `string` | No | — |
| `recordingAvailable` | `boolean` | No | — |
| `metadata` | `object` | No | — |
| `extensions` | `object[]` | No | — |

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

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id: string,
>   runtimeId: string,
>   version: string
> }[]
> ```

***

### list

`browsers.list`

GET /browsers — paginated browsers, filter by active/stopped

**Risk:** `read`

```ts theme={null}
await corsair.browseruse.api.browsers.list({ filterBy: 'active', pageSize: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `pageSize` | `number` | No | — |
| `pageNumber` | `number` | No | — |
| `filterBy` | `active \| stopped` | No | — |
| `metadata` | `string[]` | No | — |
| `agentSessionId` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | — |
| `totalItems` | `number` | Yes | — |
| `pageNumber` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   id: string,
>   status: active | stopped,
>   liveUrl?: string | null,
>   cdpUrl?: string | null,
>   timeoutAt: string,
>   startedAt: string,
>   finishedAt?: string | null,
>   proxyUsedMb?: string,
>   proxyCost?: string,
>   browserCost?: string,
>   agentSessionId?: string | null,
>   recordingUrl?: string | null,
>   recordingAvailable?: boolean,
>   metadata?: {
>   },
>   extensions?: {
>     id: string,
>     runtimeId: string,
>     version: string
>   }[]
> }[]
> ```

***

### stop

`browsers.stop`

PATCH /browsers/\{id} — stop a browser and refund unused time

**Risk:** `write`

```ts theme={null}
await corsair.browseruse.api.browsers.stop({ id: '<browser-id>' });
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `status` | `active \| stopped` | Yes | — |
| `liveUrl` | `string` | No | — |
| `cdpUrl` | `string` | No | — |
| `timeoutAt` | `string` | Yes | — |
| `startedAt` | `string` | Yes | — |
| `finishedAt` | `string` | No | — |
| `proxyUsedMb` | `string` | No | — |
| `proxyCost` | `string` | No | — |
| `browserCost` | `string` | No | — |
| `agentSessionId` | `string` | No | — |
| `recordingUrl` | `string` | No | — |
| `recordingAvailable` | `boolean` | No | — |
| `metadata` | `object` | No | — |
| `extensions` | `object[]` | No | — |

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

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id: string,
>   runtimeId: string,
>   version: string
> }[]
> ```

***

## Runs

### cancel

`runs.cancel`

POST /runs/\{id}/cancel — cancel an in-flight run

**Risk:** `write`

```ts theme={null}
await corsair.browseruse.api.runs.cancel({ id: '<run-id>' });
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `task` | `string` | Yes | — |
| `title` | `string` | No | — |
| `model` | `string` | Yes | — |
| `contextLimit` | `number` | Yes | — |
| `status` | `queued \| dispatching \| running \| completed \| failed \| cancelled` | Yes | — |
| `result` | `string` | No | — |
| `output` | `any` | No | — |
| `error` | `string` | No | — |
| `sessionId` | `string` | Yes | — |
| `workspaceId` | `string` | No | — |
| `judgement` | `object` | No | — |
| `totalInputTokens` | `number` | Yes | — |
| `totalOutputTokens` | `number` | Yes | — |
| `totalCostUsd` | `string` | Yes | — |
| `createdAt` | `string` | Yes | — |
| `updatedAt` | `string` | Yes | — |

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

***

### create

`runs.create`

POST /runs — start a browser agent run for a natural-language task

**Risk:** `write`

```ts theme={null}
await corsair.browseruse.api.runs.create({ task: 'Find the top 3 trending repos on GitHub today' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `task` | `string` | Yes | — |
| `model` | `mimo-v2.6-pro \| mimo-v2.6-flash \| deepseek-v4.1-flash \| glm-5.2 \| grok-4.5 \| grok-4.6 \| glm-5.3-flash \| deepseek-v4-flash-vision \| kimi-k3 \| minimax-m3 \| claude-opus-4.7 \| claude-opus-4.8 \| claude-opus-5 \| claude-opus-5-5 \| claude-fable-5 \| claude-sonnet-5 \| claude-sonnet-5-5 \| gpt-5.5 \| gpt-5.6 \| gpt-6-astra \| gpt-6-sol \| gpt-6.1-sol \| gpt-6-luna \| gpt-5.6-sol \| gpt-5.6-terra \| gpt-5.6-luna \| gemini-3.6-flash \| gemini-3.5-flash \| gemini-3.1-pro \| gemini-3-flash \| bu-ultrafast \| bu-fast` | No | — |
| `modelParams` | `object` | No | — |
| `outputSchema` | `object` | No | — |
| `sessionId` | `string` | No | — |
| `workspaceId` | `string` | No | — |
| `browserSettings` | `object` | No | — |
| `keepAlive` | `number` | No | — |
| `agentmail` | `boolean` | No | — |
| `agentcardWalletId` | `string` | No | — |
| `stripeLinkConnectionId` | `string` | No | — |
| `agenticAutofillGrantId` | `string` | No | — |
| `attachedFileIds` | `string[]` | No | — |
| `secretBindings` | `object[]` | No | — |
| `opVaultId` | `string` | No | — |
| `opVaultAllowedDomains` | `string[]` | No | — |
| `judge` | `object` | No | — |
| `maxCostUsd` | `number \| string` | No | — |

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

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

> [accordion] browserSettings full type
>
> ```ts theme={null}
> {
>   profileId?: string | null,
>   proxyCountryCode?: ad | ae | af | ag | ai | al | am | an | ao | aq | ar | as | at | au | aw | 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 | co | cr | cs | 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 | 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 | 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 | uk | us | uy | uz | va | vc | ve | vg | vi | vn | vu | wf | ws | xk | ye | yt | za | zm | zw | null,
>   customProxy?: {
>     host: string,
>     port: number,
>     username?: string | null,
>     password?: string | null,
>     ignoreCertErrors?: boolean
>   } | null,
>   screenWidth?: number | null,
>   screenHeight?: number | null,
>   allowResizing?: boolean | null,
>   record?: boolean | null,
>   extensionIds?: string[]
> }
> ```

> [accordion] secretBindings full type
>
> ```ts theme={null}
> {
>   alias: string,
>   source: {
>     type: inline,
>     value: string
>   } | {
>     type: onepassword,
>     integrationId: string,
>     vaultId: string,
>     itemId: string,
>     fieldId: string
>   },
>   allowedDomains: string[]
> }[]
> ```

> [accordion] judge full type
>
> ```ts theme={null}
> {
>   context?: string | null
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `status` | `queued \| dispatching \| running \| completed \| failed \| cancelled` | Yes | — |
| `model` | `string` | Yes | — |
| `sessionId` | `string` | Yes | — |
| `workspaceId` | `string` | Yes | — |
| `eventsUrl` | `string` | Yes | — |
| `missingFileIds` | `string[]` | No | — |
| `skippedVaultItems` | `string[]` | No | — |

***

### get

`runs.get`

GET /runs/\{id} — full run once status is terminal: result, tokens, cost

**Risk:** `read`

```ts theme={null}
await corsair.browseruse.api.runs.get({ id: '<run-id>' });
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `task` | `string` | Yes | — |
| `title` | `string` | No | — |
| `model` | `string` | Yes | — |
| `contextLimit` | `number` | Yes | — |
| `status` | `queued \| dispatching \| running \| completed \| failed \| cancelled` | Yes | — |
| `result` | `string` | No | — |
| `output` | `any` | No | — |
| `error` | `string` | No | — |
| `sessionId` | `string` | Yes | — |
| `workspaceId` | `string` | No | — |
| `judgement` | `object` | No | — |
| `totalInputTokens` | `number` | Yes | — |
| `totalOutputTokens` | `number` | Yes | — |
| `totalCostUsd` | `string` | Yes | — |
| `createdAt` | `string` | Yes | — |
| `updatedAt` | `string` | Yes | — |

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

***

### getStatus

`runs.getStatus`

GET /runs/\{id}/status — cheap poll until completed, failed, or cancelled

**Risk:** `read`

```ts theme={null}
await corsair.browseruse.api.runs.getStatus({ id: '<run-id>' });
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `queued \| dispatching \| running \| completed \| failed \| cancelled` | Yes | — |

***


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