Request

Method and path	POST`/v1/sessions/{id}/browser/actions`
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
`actions`required	`array`	–	–	1 to 100 items.
`timeoutMs`	`integer`	`30000`	–	Time limit of each action (ms). From 1000 to 120000.

Each item of actions[] is one of these kinds, picked by action:

action: "goto" Value: {url, title, status}.

Name	Type	Default	Allowed values	Description
`url`required	`string`	–	–
`waitUntil`	`string`	`load`	`load`, `domcontentloaded`, `networkidle`, `commit`

action: "click" A selector, or viewport coordinates x and y. count 2 is a double click, 3 a triple click.

Name	Type	Default	Allowed values	Description
`selector`	`string`	–	–
`x`	`number`	–	–
`y`	`number`	–	–
`button`	`string`	`left`	`left`, `right`, `middle`
`count`	`integer`	`1`	`1`, `2`, `3`
`modifiers`	`string[]`	–	–	Keys held down during the action, e.g. ["Shift"]. Up to 10 items.

action: "fill"

Name	Type	Default	Allowed values	Description
`selector`required	`string`	–	–
`value`required	`string`	–	–

action: "type" Types text, or a credential's value without it passing through the caller (credential and, for a password, field). A credential with sites goes only into the field selector names, on one of its sites.

Name	Type	Default	Allowed values	Description
`text`	`string`	–	–
`selector`	`string`	–	–
`delayMs`	`integer`	–	–
`credential`	`string`	–	–	A credential (scope "agent" or "all") whose value is typed instead of text.
`field`	`string`	–	`username`, `password`, `otp`	A password credential's field (left out for a secret); otp waits for a fresh code with codeSource push or url.
`allowWithExtensions`	`boolean`	`false`	–	Allow typing a credential in a session with Chrome extensions.

action: "press"

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

action: "key" A key combination held together ("Control+A" or ["Control", "A"]); a string may hold several combinations separated by spaces, pressed one after the other. Names are Playwright's; ctrl, cmd, super, Return, Page_Down, ESC, ARROWLEFT and similar spellings are accepted.

Name	Type	Default	Allowed values	Description
`keys`required	`string \| string[]`	–	–
`holdMs`	`integer`	–	–	Keep the keys down this long. From 0 to 10000.

action: "scroll" Moves the pointer to x/y when given, then turns the wheel (pixels).

Name	Type	Default	Allowed values	Description
`deltaY`	`number`	–	–	From -50000 to 50000.
`deltaX`	`number`	–	–	From -50000 to 50000.
`x`	`number`	–	–
`y`	`number`	–	–
`modifiers`	`string[]`	–	–	Keys held down during the action, e.g. ["Shift"]. Up to 10 items.

action: "move" Moves the pointer to x/y, or by dx/dy from where it is, in a straight line through steps points. Value: {x, y}.

Name	Type	Default	Allowed values	Description
`x`	`number`	–	–
`y`	`number`	–	–
`dx`	`number`	–	–
`dy`	`number`	–	–
`steps`	`integer`	`1`	–	From 1 to 100.
`modifiers`	`string[]`	–	–	Keys held down during the action, e.g. ["Shift"]. Up to 10 items.

action: "hover" Moves the pointer over an element (selector) or to x/y.

Name	Type	Default	Allowed values
`selector`	`string`	–	–
`x`	`number`	–	–
`y`	`number`	–	–

action: "mouse_down" | "mouse_up" Presses or releases a mouse button where the pointer is.

Name	Type	Default	Allowed values	Description
`button`	`string`	`left`	`left`, `right`, `middle`

action: "drag" Presses at from, moves to to in steps points, releases; or presses at the first point of path and follows it (steps points per segment). Value: {from:{x,y}, to:{x,y}}.

Name	Type	Default	Allowed values	Description
`from`	`object \| string`	–	–	{x, y}, or a selector (the element's centre, scrolled into view).
`from.x`required	`number`	–	–	At least 0.
`from.y`required	`number`	–	–	At least 0.
`to`	`object \| string`	–	–	{x, y}, or a selector (the element's centre, scrolled into view).
`to.x`required	`number`	–	–	At least 0.
`to.y`required	`number`	–	–	At least 0.
`path`	`object[]`	–	–	2 to 200 items.
`path[].x`required	`number`	–	–	At least 0.
`path[].y`required	`number`	–	–	At least 0.
`steps`	`integer`	–	–	Default 10 for from/to, 1 for a path. From 1 to 100.
`button`	`string`	`left`	`left`, `right`, `middle`
`modifiers`	`string[]`	–	–	Keys held down during the action, e.g. ["Shift"]. Up to 10 items.

action: "cursor" Value: {x, y}, the pointer's position on the tab (the last place the API moved it to; 0, 0 before any move).

No other fields.

action: "wait" Wait for a selector, or a number of milliseconds.

Name	Type	Default	Allowed values	Description
`selector`	`string`	–	–
`ms`	`integer`	–	–

action: "screenshot" Value: {data (base64), mimeType}; with maxWidth or cursor also {width, height, scale} (image pixels per CSS pixel).

Name	Type	Default	Allowed values	Description
`fullPage`	`boolean`	–	–
`format`	`string`	`png`	`png`, `jpeg`
`quality`	`integer`	–	–	From 1 to 100.
`maxWidth`	`integer`	–	–	Scale down to at most this width (aspect ratio kept). Viewport screenshots only. From 100 to 3840.
`cursor`	`boolean`	–	–	Draw the pointer on the image. Viewport screenshots only.

action: "content" Value: {content, url, title}.

Name	Type	Default	Allowed values	Description
`format`	`string`	`markdown`	`markdown`, `html`, `text`

action: "evaluate" Value: what the expression returns.

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

action: "upload" Sets a file input to a file in the session's workspace.

Name	Type	Default	Allowed values	Description
`selector`required	`string`	–	–
`path`required	`string`	–	–	A file of the session's workspace (relative to it, or absolute under it). 400 for a path outside the workspace, a missing file, a folder, or a link that leads out of the workspace.

action: "select" Picks an option of a select element by label or value.

Name	Type	Default	Allowed values	Description
`selector`required	`string`	–	–
`option`required	`string`	–	–

action: "elements" The page as a model sees it. Value: {url, title, text, elements, count}.

No other fields.

action: "tabs" Value: {current, tabs:[{index, url, title}]}.

No other fields.

action: "newTab" Value: {index}.

Name	Type	Default	Allowed values	Description
`url`	`string`	–	–

action: "switchTab"

Name	Type	Default	Allowed values	Description
`index`required	`integer`	–	–	At least 0.

action: "closeTab" Closes the tab at index, or the current one.

Name	Type	Default	Allowed values	Description
`index`	`integer`	–	–	At least 0.

action: "back" | "forward" | "reload"

No other fields.

action: "step" One plain-English step ("click Sign in", "type %password% into the password field"): a fast model picks one action and the server runs it. Variable values are substituted on the server and never sent to the model.

Name	Type	Default	Allowed values	Description
`instruction`required	`string`	–	–
`variables`	`object`	–	–
`credentials`	`string[]`	–	–	Credentials usable as placeholders (%NAME%, %NAME.username%, %NAME.password%, %NAME.otp%; scope "agent" or "all"), with their own sites (checked on the field's frame) and shell rule. In a session whose profile links a password credential, its placeholders work too. The step's result never shows their values. Up to 50 items.
`allowWithExtensions`	`boolean`	`false`	–	Allow `credentials` in a session with Chrome extensions, which can read every typed value (400 `variables_with_extensions` otherwise; a profile's credential is not offered). Logs a warning in the session's events. Ignored in a script's step(): only the browser/script agreement counts.
`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`	`string`	–	–
`targetId`	`string`	–	–	A tab's target id.

action: "extract" Structured data from the current page (instruction and/or JSON schema).

Name	Type	Default	Allowed values	Description
`instruction`	`string`	–	–
`schema`	`object`	–	–	A JSON Schema.
`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`	`string`	–	–
`targetId`	`string`	–	–

action: "login" Signs the session's browser in with a password credential (default: the one the session's profile links): a short agent run in the session (at most 15 steps, only that credential and its sites, browser tools only). Value {url, title, runId} (url without query or fragment); fails with credential_login_failed (error: the run's last step), credential_code_timeout or credential_link_wrong_site. Counts as an agent run.

Name	Type	Default	Allowed values	Description
`credential`	`string`	–	–	Pattern: `^[A-Z_][A-Z0-9_]*$`.
`url`	`string`	–	–	The sign-in page; one of the credential's sites (default its first site).
`allowWithExtensions`	`boolean`	`false`	–

More examples:

list

{  "actions": [    {      "action": "goto",      "url": "https://example.com"    },    {      "action": "content",      "format": "markdown"    }  ]}

step

{  "action": "step",  "instruction": "type %email% into the email field",  "variables": {    "email": "ada@example.com"  }}

Bare strings are plain-English steps

{  "actions": [    {      "action": "goto",      "url": "https://example.com/login"    },    "click Sign in",    {      "action": "screenshot",      "maxWidth": 1024    }  ]}

Drag a slider, double-click a word, press a shortcut

{  "actions": [    {      "action": "drag",      "from": "#volume-handle",      "to": {        "x": 400,        "y": 200      },      "steps": 20    },    {      "action": "move",      "x": 640,      "y": 360,      "steps": 10    },    {      "action": "click",      "x": 190,      "y": 112,      "count": 2    },    {      "action": "click",      "selector": "#file",      "button": "right"    },    {      "action": "key",      "keys": "Control+A"    },    {      "action": "drag",      "path": [        {          "x": 100,          "y": 100        },        {          "x": 150,          "y": 120        },        {          "x": 200,          "y": 180        }      ]    },    {      "action": "cursor"    },    {      "action": "screenshot",      "maxWidth": 640,      "cursor": true    }  ]}

curl -X POST "https://api.boxline.dev/v1/sessions/$SESSION_ID/browser/actions" \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{    "actions": [      {"action": "goto", "url": "https://example.com"},      "click the Sign in link"    ]  }'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst results = await bx.sessions.actions("SESSION_ID", [  { action: "goto", url: "https://example.com" },  "click the Sign in link",]);for (const r of results) console.log(r.action, r.ok, r.value);

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLresults = bx.sessions.actions("SESSION_ID", [    {"action": "goto", "url": "https://example.com"},    "click the Sign in link",])for r in results:    print(r["action"], r["ok"], r.get("value"))

Responses

200 OK

One result per action run.

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)

Fields

Name	Type	Default	Allowed values	Description
`results`	`object[]`	–	–
`results[].ok`	`boolean`	–	–
`results[].action`	`string`	–	–
`results[].value`	`any`	–	–	The action's result (see each action; StepValue for step).
`results[].text`	`string`	–	–	One line saying what happened ("Dragged from (180, 200) to (400, 200) in 10 steps"); never typed text.
`results[].error`	`string`	–	–
`results[].code`	`string`	–	–	A stable error code when there is one, e.g. captcha_timeout, out_of_viewport, model_refused (extract), tab_crashed / tab_hung (the tab was replaced by a fresh one on its last address; the action did not run), credential_code_timeout, credential_link_wrong_site, credential_login_failed (login).
`results[].runId`	`string`	–	–	login: the agent run that signed in (on success also in value).
`results[].ms`	`integer`	–	–

Response 200

{  "results": [    {      "ok": false,      "action": "…",      "value": null,      "text": "…",      "error": "…",      "code": "…",      "runId": "…",      "ms": 0    }  ]}

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.
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.
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 body

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

Learn more

StepsThe 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.