Request

Method and path	PATCH`/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`.
Rate limit	Yes. See Rate limits for the numbers and headers.

Path parameters

Name	Type	Default	Allowed values	Description
`id`required	`string`	–	–

Body

JSON with content-type: application/json. Required.

Name	Type	Default	Allowed values	Description
`name`	`string`	–	–	1 to 100 characters.
`instruction`	`string`	–	–	Up to 20000 characters.
`variables`	`object[]`	–	–	Up to 50 items.
`variables[].name`required	`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[] \| null`	–	–	The whole new list of credential names (null or [] removes them); checked as on create. Up to 50 items.
`output`	`object \| null`	–	–
`session`	`object \| null`	–	–	A SessionSpec, or null to remove it.
`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`required	`integer`	–	–	From 200 to 3840.
`session.viewport.height`required	`integer`	–	–	From 200 to 2160.
`session.userMetadata`	`object`	–	–
`session.profile`	`object`	–	–
`session.profile.id`required	`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`required	`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.password`	`string`	–	–	Stored encrypted; never returned.
`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`	`false`	–	Needed for a task with secret variables or credentials and a session with extensions (400 `variables_with_extensions` otherwise).
`model`	`object \| null`	–	–
`maxSteps`	`integer \| null`	–	–	null: no step limit. From 1 to 1000.
`maxCostUsd`	`number \| null`	–	–	From 0.01 to 100.
`notifyOnFailure`	`string \| null`	–	`email`, `null`
`schedule`	`object \| null`	–	–
`schedule.cron`	`string`	–	–	Five fields (minute hour day-of-month month day-of-week), names JAN–DEC and SUN–SAT, or @hourly, @daily, @weekly, @monthly, @yearly. At most every 5 minutes.
`schedule.timezone`	`string`	`UTC`	–	An IANA time zone; the cron is read on its clock.
`schedule.variables`	`object`	–	–	Values for non-secret variables.
`schedule.enabled`	`boolean`	`true`	–

curl -X PATCH "https://api.boxline.dev/v1/tasks/$TASK_ID" \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{    "schedule": {      "cron": "0 9 * * MON-FRI",      "timezone": "Europe/London",      "variables": {"category": "Poetry"}    }  }'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst task = await bx.tasks.update("TASK_ID", {  schedule: {    cron: "0 9 * * MON-FRI",    timezone: "Europe/London",    variables: { category: "Poetry" },  },});console.log(task.schedule?.nextRunAt); // when it runs next

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLtask = bx.tasks.update("TASK_ID",     schedule={        "cron": "0 9 * * MON-FRI",        "timezone": "Europe/London",        "variables": {"category": "Poetry"},    },)print(task["schedule"]["nextRunAt"])  # when it runs next

Responses

200 OK

The task now.

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.

Response 200

{  "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
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.
404 Not Found	`not_found`, `invite_not_found`, `provider_unavailable`	No such thing in this project (or organization), or no such route.
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.

Error body

{  "error": {    "code": "not_found",    "message": "session not found",    "requestId": "req_4fJx0aQm2Lk9Pz7N"  }}

Learn more

TasksThe guide to this part of the API, with more examples.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.