Create a session
Claims a warm machine with a browser and/or a shell. Limited to 120 per minute per project, and to the plan's concurrent sessions (429 concurrency_limit). 503 no_capacity when no machine is free in time. browser (default true) and shell (default false) choose the kind: browser only, shell only ({browser: false, shell: true}) or both. Without a browser connectUrl and liveUrl are null; without a shell terminalUrl is.
POST
/v1/sessionsRequest
| Method and path | POST/v1/sessions |
|---|---|
| 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. |
| Safe retries | Send an Idempotency-Key header to retry without creating anything twice. See Idempotency keys. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Headers
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
Idempotency-Key | string | – | – | Makes a retry safe: the same key and body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of creating something twice. 1 to 255 printable ASCII characters without spaces, e.g. a UUID. Keys belong to the project (a new API key is replayed only to its caller). At most 300 new keys per minute per project (429). 1 to 255 characters. |
Body
JSON with content-type: application/json. Optional: you can leave the body out.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
browser | boolean | object | – | – | true or omitted: a browser with the defaults; false: none; an object: a browser with these settings. |
browser.mode | string | standard | standard, realistic | realistic puts the clock and language on the proxy's country. It never changes what the browser reports about itself. |
browser.locale | string | – | – | BCP 47, e.g. de-DE. Wins over the mode. |
browser.timezone | string | – | – | IANA, e.g. Europe/Berlin. Wins over the mode. |
shell | boolean | false | – | A bash shell with Python, Node, ffmpeg and sudo, sharing /workspace. |
timeout | integer | 300 | – | Seconds, up to the plan's maxTimeoutSeconds (402 plan_limit). At least 60. |
idleTimeout | integer | null | – | – | Opt-in (default off): the session stops (stopReason idle) after this many seconds without activity: 30 to its timeout. Activity: CDP commands through the gateway, live-view input, terminal keys, exec, files calls, actions and steps, scripts, agent steps and messages; an agent run working in the session (or one that can still be resumed) counts the whole time. Checked every few seconds. null switches it off (PATCH). At least 30. |
keepAlive | boolean | false | – | Keep a browser-only session after its last client disconnects. |
viewport | object | – | – | |
viewport.widthrequired | integer | – | – | From 200 to 3840. |
viewport.heightrequired | integer | – | – | From 200 to 2160. |
userMetadata | object | – | – | |
profile | object | – | – | |
profile.idrequired | string | – | – | |
profile.persist | boolean | false | – | Save the browser's logins back into the profile at the end. |
recordSession | boolean | true | – | |
setup | string[] | – | – | Shell commands run in order when the session starts, and again after a resume (needs shell). Up to 20 items. |
proxy | boolean | null | object | object[] | – | – | true = a residential US proxy; an object = one proxy; a list = rules by site (at most 10); null or false = none. |
proxy.typerequired | 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.password | string | – | – | Stored encrypted; never returned. |
proxy[].domainPattern | string | – | – | Up to 256 characters. |
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. |
blockAds | boolean | false | – | Refuse requests to ad and tracker sites inside the machine (its local proxy), with or without a session proxy. Blocked requests are counted in blockedRequests and reported in lifecycle events. |
cookieBanners | string | reject | reject, off | reject: answer consent banners of the common platforms with "Reject all" or "Necessary only" (never accept), else hide them, in every tab and frame. Each answer is a lifecycle event. |
extensions | string[] | – | – | Uploaded extensions (POST /v1/extensions) to load into the browser; needs the plan feature extensions. Up to 10 items. |
env | object | – | – | Variables for the session's shell (needs shell): new terminals, exec, scripts and setup commands get them, and they are set again on every new machine (resume, recovery). Names like the shell's ([A-Za-z_][A-Za-z0-9_]*, not PATH, HOME or BOXLINE_*), 64 KB together. Kept sealed; the session shows the names only. |
credentials | string[] | – | – | Credentials exported into the shell, one variable per field: a secret as $NAME, a password as $NAME_USERNAME and $NAME_PASSWORD (and boxline-otp NAME prints its 2FA code). Needs shell; the credential needs scope "shell" or "all", or shell true (else 400 credential_not_for_shell). Kept in the machine's memory only (never a file in /workspace), set again on every new machine, and hidden in exec, script and terminal output. Up to 50 items. |
More examples:
{"browser":false,"shell":true}{"timeout":600,"viewport":{"width":1280,"height":720}}{ "shell": true, "setup": [ "pip install yt-dlp" ], "userMetadata": { "job": "nightly" }}{ "proxy": { "type": "residential", "country": "DE" }, "browser": { "mode": "realistic" }}{ "blockAds": true, "cookieBanners": "reject", "extensions": [ "ext_Q2x9L0aPz7NmK3Jb" ]}curl -X POST "https://api.boxline.dev/v1/sessions" \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "Idempotency-Key: $(uuidgen)"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst session = await bx.sessions.create();console.log(session.id, session.connectUrl); // connectUrl is null without a browserfrom boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLsession = bx.sessions.create()print(session.id, session.connect_url) # connect_url is None without a browserboxline sessions createResponses
201 Created
The running session.
Headers
RateLimit-Limit: Requests allowed in the current window of this route's limit. (Rate limits)RateLimit-Remaining: Requests left in the current window. (Rate limits)RateLimit-Reset: Seconds until the window starts again. (Rate limits)Idempotent-Replayed:truewhen this is the kept response of an earlier request with the same Idempotency-Key. (Idempotency keys)
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 |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 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. |
| 403 Forbidden | project_suspended, organization_suspended, role_forbidden, forbidden, extension_denied, cross_site_request, console_login_required, impersonating, invite_email_mismatch, email_unconfirmed | Not allowed. |
| 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. |
| 422 Unprocessable Content | idempotency_mismatch | This Idempotency-Key was already used for a different request. |
| 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.