List tasks
List tasks.
GET
/v1/tasksRequest
| Method and path | GET/v1/tasks |
|---|---|
| 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. |
Query parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
limit | integer | 50 | – | From 1 to 200. |
after | string | – | – | The next value of the previous page (same filters and sort). Opaque; do not build it yourself. |
curl "https://api.boxline.dev/v1/tasks" \ -H "x-api-key: $BOXLINE_API_KEY"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLfor await (const t of bx.tasks.list()) console.log(t.id, t.name, t.schedule?.nextRunAt ?? "no schedule");from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLfor t in bx.tasks.list(): print(t["id"], t["name"], (t["schedule"] or {}).get("nextRunAt", "no schedule"))boxline tasks list # the newest 20, with their schedulesboxline tasks list --all # every taskResponses
200 OK
A page of tasks, newest first.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
data | object[] | – | – | |
data[].id | string | – | – | |
data[].name | string | – | – | |
data[].instruction | string | – | – | |
data[].variables | object[] | – | – | |
data[].variables[].name | string | – | – | Up to 64 characters. Pattern: ^[A-Za-z_][A-Za-z0-9_]*$. |
data[].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. |
data[].variables[].default | string | null | – | – | Non-secret variables only. Up to 8000 characters. |
data[].variables[].description | string | null | – | – | Up to 500 characters. |
data[].variables[].origins | string[] | null | – | – | Secret variables only (as agent variables' origins). 1 to 20 items. |
data[].variables[].shell | boolean | false | – | Secret variables only: bash commands may use it. |
data[].credentials | string[] | – | – | Names of the credentials its runs get (never values). |
data[].output | object | null | – | – | |
data[].session | object | null | – | – | The settings of each run's own session (env as a list of names; the proxy without its password). |
data[].session.browser | boolean | object | – | – | true or omitted: a browser with the defaults; false: none; an object: a browser with these settings. |
data[].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. |
data[].session.browser.locale | string | – | – | BCP 47, e.g. de-DE. Wins over the mode. |
data[].session.browser.timezone | string | – | – | IANA, e.g. Europe/Berlin. Wins over the mode. |
data[].session.shell | boolean | false | – | A bash shell with Python, Node, ffmpeg and sudo, sharing /workspace. |
data[].session.timeout | integer | 300 | – | Seconds, up to the plan's maxTimeoutSeconds (402 plan_limit). At least 60. |
data[].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. |
data[].session.keepAlive | boolean | false | – | Keep a browser-only session after its last client disconnects. |
data[].session.viewport | object | – | – | |
data[].session.viewport.width | integer | – | – | From 200 to 3840. |
data[].session.viewport.height | integer | – | – | From 200 to 2160. |
data[].session.userMetadata | object | – | – | |
data[].session.profile | object | – | – | |
data[].session.profile.id | string | – | – | |
data[].session.profile.persist | boolean | false | – | Save the browser's logins back into the profile at the end. |
data[].session.recordSession | boolean | true | – | |
data[].session.setup | string[] | – | – | Shell commands run in order when the session starts, and again after a resume (needs shell). Up to 20 items. |
data[].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. |
data[].session.proxy.type | string | – | residential, datacenter, custom | |
data[].session.proxy.country | string | – | – | Two-letter country code (residential and datacenter). |
data[].session.proxy.state | string | – | – | Residential, US states, e.g. us_california (implies US). |
data[].session.proxy.city | string | – | – | Residential, e.g. los_angeles (needs country). |
data[].session.proxy.ip | string | – | sticky, rotating | Default sticky for sessions and crawls, rotating for fetch, screenshot, pdf and extract. |
data[].session.proxy.scope | string | browser | browser, all | all also routes the session's shell. |
data[].session.proxy.server | string | – | – | custom: your proxy, http://host:port or https://host:port, on a public address. |
data[].session.proxy.username | string | – | – | |
data[].session.proxy[].domainPattern | string | – | – | Up to 256 characters. |
data[].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. |
data[].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. |
data[].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. |
data[].session.extensions | string[] | – | – | Uploaded extensions (POST /v1/extensions) to load into the browser; needs the plan feature extensions. Up to 10 items. |
data[].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. |
data[].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. |
data[].allowWithExtensions | boolean | – | – | |
data[].model | object | null | – | – | |
data[].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). |
data[].model.model | string | – | – | |
data[].maxSteps | integer | null | – | – | null: no step limit (30 when the task never set one). |
data[].maxCostUsd | number | null | – | – | |
data[].notifyOnFailure | string | null | – | – | |
data[].schedule | object | null | – | – | |
data[].schedule.cron | string | – | – | |
data[].schedule.timezone | string | – | – | |
data[].schedule.variables | object | – | – | |
data[].schedule.enabled | boolean | – | – | |
data[].schedule.nextRunAt | string | null | – | – | Null while switched off. Format: date-time. |
data[].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. |
data[].lastRunAt | string | null | – | – | Format: date-time. |
data[].lastRun | object | null | – | – | |
data[].lastRun.id | string | – | – | |
data[].lastRun.status | string | – | queued, running, paused, completed, failed, canceled | |
data[].lastRun.errorCode | string | null | – | – | Why it stopped (max_steps, session_timeout, …), as on its agent run; null while working or when completed. |
data[].lastRun.createdAt | string | – | – | Format: date-time. |
data[].lastRun.finishedAt | string | null | – | – | Format: date-time. |
data[].createdAt | string | – | – | Format: date-time. |
data[].updatedAt | string | – | – | Format: date-time. |
next | string | null | – | – | Pass it back as after for the next page; null on the last page. |
{ "data": [ { "id": "task_Hk2Lq8Zx0Vb5Nm1C", "name": "Work account", "instruction": "…", "variables": [ { "name": "Work account", "secret": false, "default": "…", "description": "…", "origins": [], "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" } ], "next": "eyJvIjoiY3JlYXRlZF9kZXNjIiwidCI6IjIwMjYtMDktMjlUMTA6MDA6MDAuMTIzNDU2WiIsImkiOiI2YzFmIn0"}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. |
{ "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.