Resume a session
The same session on a fresh machine, as it was when it stopped (tabs with their history, cookies, storage, files, each shell's directory and exported variables; not running processes or page memory). 409 nothing_saved when nothing was saved (a machine lost before its first checkpoint, a session from before stop and resume existed); 409 session_not_stopped for a deleted session; 409 conflict while another running session holds its browser profile; 429 concurrency_limit; 402 spend_limit or out_of_credit.
POST
/v1/sessions/{id}/resumeRequest
| Method and path | POST/v1/sessions/{id}/resume |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
curl -X POST "https://api.boxline.dev/v1/sessions/$SESSION_ID/resume" \ -H "x-api-key: $BOXLINE_API_KEY"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst session = await bx.sessions.resume("SESSION_ID");console.log(session.status); // "RUNNING"from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLsession = bx.sessions.resume("SESSION_ID")print(session.status) # RUNNINGboxline sessions resume $SESSION_IDResponses
200 OK
The running session.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
id | string | – | – | |
status | string | – | RUNNING, STOPPED, DELETED, ERROR | RUNNING; STOPPED (saved, no machine, free); DELETED (ended for good, its data gone); ERROR (only a session that never started). |
projectId | string | – | – | |
region | string | – | – | |
browser | boolean | – | – | |
shell | boolean | – | – | |
keepAlive | boolean | – | – | |
timeout | integer | – | – | Seconds. |
idleTimeout | integer | null | – | – | Seconds without activity after which it stops (stopReason idle); null: off. |
createdAt | string | – | – | Format: date-time. |
startedAt | string | null | – | – | Format: date-time. |
expiresAt | string | – | – | Format: date-time. |
stoppedAt | string | null | – | – | When it stopped (null while it runs; cleared by a resume). Format: date-time. |
stopReason | string | null | – | – | requested, timeout, idle, no_clients, agent_run, task, machine_lost, api_restart, account_recovered, suspended, spend_limit or out_of_credit. |
deletesAt | string | null | – | – | When a stopped session is deleted automatically: stoppedAt plus the plan's retentionDays, fixed when it stops. Format: date-time. |
deletedAt | string | null | – | – | Format: date-time. |
deleteReason | string | null | – | requested, retention, null | |
connectUrl | string | null | – | – | CDP WebSocket for Playwright/Puppeteer (null without a browser or unless the session is running). Treat it like a password. |
liveUrl | string | null | – | – | The live view page (null without a browser |
terminalUrl | string | null | – | – | The terminal WebSocket (null without a shell). Treat it like a password. |
proxy | null | object | object[] | – | – | The session's proxy as given, without passwords. |
proxy.type | string | – | residential, datacenter, custom | |
proxy.country | string | – | – | Two-letter country code (residential and datacenter). |
proxy.state | string | – | – | Residential, US states, e.g. us_california (implies US). |
proxy.city | string | – | – | Residential, e.g. los_angeles (needs country). |
proxy.ip | string | – | sticky, rotating | Default sticky for sessions and crawls, rotating for fetch, screenshot, pdf and extract. |
proxy.scope | string | browser | browser, all | all also routes the session's shell. |
proxy.server | string | – | – | custom: your proxy, http://host:port or https://host:port, on a public address. |
proxy.username | string | – | – | |
proxy[].domainPattern | string | – | – | Up to 256 characters. |
browserSettings | object | – | – | What is in force (locale and timezone null = the browser's own default). |
browserSettings.mode | string | – | standard, realistic | |
browserSettings.locale | string | null | – | – | |
browserSettings.timezone | string | null | – | – | |
viewport | object | null | – | – | |
viewport.width | integer | – | – | From 200 to 3840. |
viewport.height | integer | – | – | From 200 to 2160. |
trajectoriesEligible | boolean | – | – | |
captcha | string | – | ask, ignore, solve | What happens when a CAPTCHA waits for a person. ask (default): agent runs and steps pause and hand over. ignore: they carry on. solve (opt-in, paid plans): the platform tries to solve it first. |
attention | object | null | – | – | A CAPTCHA waiting (or being solved), else null. |
attention.type | string | – | captcha | |
attention.kind | string | – | recaptcha, hcaptcha, turnstile, cloudflare, datadome, arkose, human | |
attention.url | string | – | – | |
attention.tabId | string | – | – | |
attention.since | string | – | – | Format: date-time. |
attention.state | string | – | solving, waiting | |
attention.reason | string | – | – | |
blockAds | boolean | – | – | |
blockedRequests | integer | – | – | Requests to ad and tracker sites refused so far (collected about every 30 s). |
cookieBanners | string | – | reject, off | "off" for sessions without a browser, and for sessions created before the option existed. |
extensions | string[] | – | – | The extension ids the session started with. |
workspacePath | string | – | – | |
profileId | string | null | – | – | |
profilePersist | boolean | – | – | Whether the session saves its sign-ins back to profileId when it ends (persist:true, or attached with fromSession). false without a profile. |
userMetadata | object | – | – | |
checkpointAt | string | null | – | – | Format: date-time. |
recoveries | integer | – | – | Times the session was brought back on a new machine after its machine stopped. |
error | string | null | – | – | |
recordSession | boolean | – | – | |
setup | string[] | – | – | |
setupStatus | string | – | none, running, done, failed | |
setupError | string | null | – | – | |
env | string[] | – | – | Names of the session's env variables (values are never returned). |
credentials | string[] | – | – | Names of the credentials its shell exports (a profile's linked one included). |
hasRecording | boolean | – | – | |
usage | object | – | – | |
usage.seconds | number | – | – | |
usage.costUsd | number | – | – |
{ "id": "6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60", "status": "RUNNING", "projectId": "prj_Hk2Lq8Zx0Vb5Nm1C", "region": "us-east-1", "browser": true, "shell": false, "keepAlive": false, "timeout": 300, "createdAt": "2026-09-29T10:00:00.000Z", "startedAt": "2026-09-29T10:00:00.000Z", "expiresAt": "2026-09-29T10:05:00.000Z", "stoppedAt": null, "stopReason": null, "deletesAt": null, "deletedAt": null, "deleteReason": null, "connectUrl": "wss://connect.boxline.dev/v1/connect?sessionId=6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60&token=…", "liveUrl": "https://api.boxline.dev/live/6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60?token=…", "terminalUrl": null, "proxy": null, "browserSettings": { "mode": "standard", "locale": null, "timezone": null }, "viewport": { "width": 1280, "height": 720 }, "trajectoriesEligible": false, "captcha": "ask", "attention": null, "blockAds": false, "blockedRequests": 0, "cookieBanners": "reject", "extensions": [], "workspacePath": "/workspace", "profileId": null, "profilePersist": false, "userMetadata": {}, "checkpointAt": null, "recoveries": 0, "error": null, "recordSession": true, "setup": [], "setupStatus": "none", "setupError": null, "env": [], "credentials": [], "hasRecording": false, "usage": { "seconds": 12.3, "costUsd": 0.00015 }}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 402 Payment Required | feature_not_in_plan, spend_limit, out_of_credit, plan_limit, spend_limit, out_of_credit, organization, project, plan, credit | The plan does not include this, a monthly allowance or spending limit is used up, the organization has no credit left, or the plan allows no more of this. spend_limit and out_of_credit carry error.details.limit: organization, project, plan or credit. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
| 409 Conflict | session_not_running, shell_disabled, browser_disabled, nothing_saved, not_resumable, invalid_state, conflict, email_taken, identity_in_use, provider_already_linked, last_sign_in_method, not_impersonating, machine_too_old, too_many_credential_values, limit_reached, terms_version_mismatch, no_project, last_owner, organization_not_empty, project_has_sessions, already_member, invite_pending, idempotency_in_progress | The current state does not allow it, or a request with this Idempotency-Key is still being answered. |
| 429 Too Many Requests | rate_limited, concurrency_limit | Too many requests, or the organization's concurrent sessions (its plan's) or the project's concurrencyCap are in use. |
| 503 Service Unavailable | no_capacity, proxy_unavailable, provider_unavailable, search_unavailable, webhooks_unavailable, mail_unavailable, browser_unreachable | No machine free in time, proxies not set up, the model provider is not configured or has no key, or web search is not set up or its provider is not answering, or webhook delivery is not set up, or an email cannot be sent, or the session's browser did not answer in time. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.