New to Corsair? See API access, authentication, and error handling.
Browsers
create
browsers.create
POST /browsers — start a cloud browser; returns cdpUrl for Playwright/Puppeteer and a liveUrl
Risk: write
await corsair.browseruse.api.browsers.create({ proxyCountryCode: 'us', timeout: 15 });
| 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 | null | No | — |
timeout | number | No | — |
browserScreenWidth | number | null | No | — |
browserScreenHeight | number | null | No | — |
allowResizing | boolean | No | — |
pdfRendererEnabled | boolean | No | — |
solveCaptchas | boolean | No | — |
enableRecording | boolean | No | — |
metadata | Record<string, string> | No | — |
customProxy | object | null | No | — |
extensionIds | string[] | No | — |
customProxy full type
customProxy full type
{
host: string,
port: number,
username?: string | null,
password?: string | null,
ignoreCertErrors?: boolean
} | null
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
status | active | stopped | Yes | — |
liveUrl | string | null | No | — |
cdpUrl | string | null | No | — |
timeoutAt | string | Yes | — |
startedAt | string | Yes | — |
finishedAt | string | null | No | — |
proxyUsedMb | string | No | — |
proxyCost | string | No | — |
browserCost | string | No | — |
agentSessionId | string | null | No | — |
recordingUrl | string | null | No | — |
recordingAvailable | boolean | No | — |
metadata | Record<string, string> | No | — |
extensions | object[] | No | — |
extensions full type
extensions full type
{
id: string,
runtimeId: string,
version: string
}[]
get
browsers.get
GET /browsers/{id} — browser status, URLs, cost, recording
Risk: read
await corsair.browseruse.api.browsers.get({ id: '<browser-id>' });
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
status | active | stopped | Yes | — |
liveUrl | string | null | No | — |
cdpUrl | string | null | No | — |
timeoutAt | string | Yes | — |
startedAt | string | Yes | — |
finishedAt | string | null | No | — |
proxyUsedMb | string | No | — |
proxyCost | string | No | — |
browserCost | string | No | — |
agentSessionId | string | null | No | — |
recordingUrl | string | null | No | — |
recordingAvailable | boolean | No | — |
metadata | Record<string, string> | No | — |
extensions | object[] | No | — |
extensions full type
extensions full type
{
id: string,
runtimeId: string,
version: string
}[]
list
browsers.list
GET /browsers — paginated browsers, filter by active/stopped
Risk: read
await corsair.browseruse.api.browsers.list({ filterBy: 'active', pageSize: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
pageSize | number | No | — |
pageNumber | number | No | — |
filterBy | active | stopped | No | — |
metadata | string[] | null | No | — |
agentSessionId | string | null | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | Yes | — |
totalItems | number | Yes | — |
pageNumber | number | Yes | — |
pageSize | number | Yes | — |
items full type
items full type
{
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?: Record<string, string>,
extensions?: {
id: string,
runtimeId: string,
version: string
}[]
}[]
stop
browsers.stop
PATCH /browsers/{id} — stop a browser and refund unused time
Risk: write
await corsair.browseruse.api.browsers.stop({ id: '<browser-id>' });
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
status | active | stopped | Yes | — |
liveUrl | string | null | No | — |
cdpUrl | string | null | No | — |
timeoutAt | string | Yes | — |
startedAt | string | Yes | — |
finishedAt | string | null | No | — |
proxyUsedMb | string | No | — |
proxyCost | string | No | — |
browserCost | string | No | — |
agentSessionId | string | null | No | — |
recordingUrl | string | null | No | — |
recordingAvailable | boolean | No | — |
metadata | Record<string, string> | No | — |
extensions | object[] | No | — |
extensions full type
extensions full type
{
id: string,
runtimeId: string,
version: string
}[]
Runs
cancel
runs.cancel
POST /runs/{id}/cancel — cancel an in-flight run
Risk: write
await corsair.browseruse.api.runs.cancel({ id: '<run-id>' });
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
task | string | Yes | — |
title | string | null | Yes | — |
model | string | Yes | — |
contextLimit | number | Yes | — |
status | queued | dispatching | running | completed | failed | cancelled | Yes | — |
result | string | null | Yes | — |
output | any | null | No | — |
error | string | null | Yes | — |
sessionId | string | Yes | — |
workspaceId | string | null | Yes | — |
judgement | object | null | No | — |
totalInputTokens | number | Yes | — |
totalOutputTokens | number | Yes | — |
totalCostUsd | string | Yes | — |
createdAt | string | Yes | — |
updatedAt | string | Yes | — |
judgement full type
judgement full type
{
} | null
create
runs.create
POST /runs — start a browser agent run for a natural-language task
Risk: write
await corsair.browseruse.api.runs.create({ task: 'Find the top 3 trending repos on GitHub today' });
| 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 | Record<string, any> | null | No | — |
outputSchema | Record<string, any> | null | No | — |
sessionId | string | null | No | — |
workspaceId | string | null | No | — |
browserSettings | object | null | No | — |
keepAlive | number | null | No | — |
agentmail | boolean | No | — |
agentcardWalletId | string | null | No | — |
stripeLinkConnectionId | string | null | No | — |
agenticAutofillGrantId | string | null | No | — |
attachedFileIds | string[] | null | No | — |
secretBindings | object[] | null | No | — |
opVaultId | string | null | No | — |
opVaultAllowedDomains | string[] | null | No | — |
judge | object | null | No | — |
maxCostUsd | number | string | null | No | — |
browserSettings full type
browserSettings full type
{
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[]
} | null
secretBindings full type
secretBindings full type
{
alias: string,
source: {
type: inline,
value: string
} | {
type: onepassword,
integrationId: string,
vaultId: string,
itemId: string,
fieldId: string
},
allowedDomains: string[]
}[] | null
judge full type
judge full type
{
context?: string | null
} | null
| 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
await corsair.browseruse.api.runs.get({ id: '<run-id>' });
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
task | string | Yes | — |
title | string | null | Yes | — |
model | string | Yes | — |
contextLimit | number | Yes | — |
status | queued | dispatching | running | completed | failed | cancelled | Yes | — |
result | string | null | Yes | — |
output | any | null | No | — |
error | string | null | Yes | — |
sessionId | string | Yes | — |
workspaceId | string | null | Yes | — |
judgement | object | null | No | — |
totalInputTokens | number | Yes | — |
totalOutputTokens | number | Yes | — |
totalCostUsd | string | Yes | — |
createdAt | string | Yes | — |
updatedAt | string | Yes | — |
judgement full type
judgement full type
{
} | null
getStatus
runs.getStatus
GET /runs/{id}/status — cheap poll until completed, failed, or cancelled
Risk: read
await corsair.browseruse.api.runs.getStatus({ id: '<run-id>' });
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
status | queued | dispatching | running | completed | failed | cancelled | Yes | — |