Stop a session
Saves the session exactly as it is (the whole browser and /workspace), frees the machine and stops billing. The recording, events, pages and agent-run steps stay. A stopped session is kept for its plan's retentionDays (see deletesAt), then deleted; resume it any time before. If its state cannot be saved the call fails and the session keeps running. 409 session_not_running for a deleted session.
POST
/v1/sessions/{id}/stopRequest
| Method and path | POST/v1/sessions/{id}/stop |
|---|---|
| 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. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
curl -X POST "https://api.boxline.dev/v1/sessions/$SESSION_ID/stop" \ -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.stop("SESSION_ID");console.log(session.status, session.data.deletesAt); // "STOPPED", the day it will be deletedfrom boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLsession = bx.sessions.stop("SESSION_ID")print(session.status, session.deletes_at) # STOPPED, the day it will be deletedboxline sessions stop $SESSION_IDResponses
200 OK
The stopped session (status STOPPED).
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. |
| 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. |
{ "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.