Get a task
Get a task.
GET
/v1/tasks/{id}Request
| Method and path | GET/v1/tasks/{id} |
|---|---|
| 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 "https://api.boxline.dev/v1/tasks/$TASK_ID" \ -H "x-api-key: $BOXLINE_API_KEY"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst task = await bx.tasks.get("TASK_ID");console.log(task.name, task.variables.map((v) => v.name), task.schedule, task.lastRunAt);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLtask = bx.tasks.get("TASK_ID")print(task["name"], [v["name"] for v in task["variables"]], task["schedule"], task["lastRunAt"])Responses
200 OK
The task.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
id | string | – | – | |
name | string | – | – | |
instruction | string | – | – | |
variables | object[] | – | – | |
variables[].name | string | – | – | Up to 64 characters. Pattern: ^[A-Za-z_][A-Za-z0-9_]*$. |
variables[].secret | boolean | false | – | The agent types it without seeing it (%name%). Its value is never stored: no default, it comes with every run, and the task cannot have a schedule. |
variables[].default | string | null | – | – | Non-secret variables only. Up to 8000 characters. |
variables[].description | string | null | – | – | Up to 500 characters. |
variables[].origins | string[] | null | – | – | Secret variables only (as agent variables' origins). 1 to 20 items. |
variables[].shell | boolean | false | – | Secret variables only: bash commands may use it. |
credentials | string[] | – | – | Names of the credentials its runs get (never values). |
output | object | null | – | – | |
session | object | null | – | – | The settings of each run's own session (env as a list of names; the proxy without its password). |
session.browser | boolean | object | – | – | true or omitted: a browser with the defaults; false: none; an object: a browser with these settings. |
session.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. |
session.browser.locale | string | – | – | BCP 47, e.g. de-DE. Wins over the mode. |
session.browser.timezone | string | – | – | IANA, e.g. Europe/Berlin. Wins over the mode. |
session.shell | boolean | false | – | A bash shell with Python, Node, ffmpeg and sudo, sharing /workspace. |
session.timeout | integer | 300 | – | Seconds, up to the plan's maxTimeoutSeconds (402 plan_limit). At least 60. |
session.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. |
session.keepAlive | boolean | false | – | Keep a browser-only session after its last client disconnects. |
session.viewport | object | – | – | |
session.viewport.width | integer | – | – | From 200 to 3840. |
session.viewport.height | integer | – | – | From 200 to 2160. |
session.userMetadata | object | – | – | |
session.profile | object | – | – | |
session.profile.id | string | – | – | |
session.profile.persist | boolean | false | – | Save the browser's logins back into the profile at the end. |
session.recordSession | boolean | true | – | |
session.setup | string[] | – | – | Shell commands run in order when the session starts, and again after a resume (needs shell). Up to 20 items. |
session.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. |
session.proxy.type | string | – | residential, datacenter, custom | |
session.proxy.country | string | – | – | Two-letter country code (residential and datacenter). |
session.proxy.state | string | – | – | Residential, US states, e.g. us_california (implies US). |
session.proxy.city | string | – | – | Residential, e.g. los_angeles (needs country). |
session.proxy.ip | string | – | sticky, rotating | Default sticky for sessions and crawls, rotating for fetch, screenshot, pdf and extract. |
session.proxy.scope | string | browser | browser, all | all also routes the session's shell. |
session.proxy.server | string | – | – | custom: your proxy, http://host:port or https://host:port, on a public address. |
session.proxy.username | string | – | – | |
session.proxy[].domainPattern | string | – | – | Up to 256 characters. |
session.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. |
session.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. |
session.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. |
session.extensions | string[] | – | – | Uploaded extensions (POST /v1/extensions) to load into the browser; needs the plan feature extensions. Up to 10 items. |
session.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. |
session.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. |
allowWithExtensions | boolean | – | – | |
model | object | null | – | – | |
model.provider | string | – | anthropic, openai, xai, google | Anthropic Claude, OpenAI, Grok (xAI), Google Gemini. Grok and Gemini have no computer use (mode computer is 400). |
model.model | string | – | – | |
maxSteps | integer | null | – | – | null: no step limit (30 when the task never set one). |
maxCostUsd | number | null | – | – | |
notifyOnFailure | string | null | – | – | |
schedule | object | null | – | – | |
schedule.cron | string | – | – | |
schedule.timezone | string | – | – | |
schedule.variables | object | – | – | |
schedule.enabled | boolean | – | – | |
schedule.nextRunAt | string | null | – | – | Null while switched off. Format: date-time. |
schedule.nextRuns | string[] | – | – | The next 3 times it fires, in UTC (the first is nextRunAt), read on the schedule's time zone and daylight-saving rules; empty while switched off. Up to 3 items. |
lastRunAt | string | null | – | – | Format: date-time. |
lastRun | object | null | – | – | |
lastRun.id | string | – | – | |
lastRun.status | string | – | queued, running, paused, completed, failed, canceled | |
lastRun.errorCode | string | null | – | – | Why it stopped (max_steps, session_timeout, …), as on its agent run; null while working or when completed. |
lastRun.createdAt | string | – | – | Format: date-time. |
lastRun.finishedAt | string | null | – | – | Format: date-time. |
createdAt | string | – | – | Format: date-time. |
updatedAt | string | – | – | Format: date-time. |
{ "id": "task_Hk2Lq8Zx0Vb5Nm1C", "name": "Work account", "instruction": "…", "variables": [ { "name": "Work account", "secret": false, "default": "…", "description": "…", "origins": [ "https://*.example.com" ], "shell": false } ], "credentials": [ "…" ], "output": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "title", "price" ] }, "session": { "browser": { "mode": "standard", "locale": "…", "timezone": "…" }, "shell": false, "timeout": 300, "idleTimeout": 30, "keepAlive": false, "viewport": { "width": 200, "height": 200 }, "userMetadata": {}, "profile": { "id": "…", "persist": false }, "recordSession": true, "setup": [ "…" ], "proxy": { "type": "residential", "country": "US", "state": "…", "city": "…", "ip": "sticky", "scope": "browser", "server": "…", "username": "…" }, "captcha": "ask", "blockAds": false, "cookieBanners": "reject", "extensions": [ "…" ], "env": {}, "credentials": [ "…" ] }, "allowWithExtensions": false, "model": { "provider": "anthropic", "model": "claude-sonnet-5-5" }, "maxSteps": 0, "maxCostUsd": 0, "notifyOnFailure": "…", "schedule": { "cron": "…", "timezone": "…", "variables": {}, "enabled": false, "nextRunAt": "2026-09-29T10:00:00.000Z", "nextRuns": [ "2026-09-29T10:00:00.000Z" ] }, "lastRunAt": "2026-09-29T10:00:00.000Z", "lastRun": { "id": "trun_Q2x9L0aPz7NmK3Jb", "status": "queued", "errorCode": "…", "createdAt": "2026-09-29T10:00:00.000Z", "finishedAt": "2026-09-29T10:00:00.000Z" }, "createdAt": "2026-09-29T10:00:00.000Z", "updatedAt": "2026-09-29T10:00:00.000Z"}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. |
{ "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.