Resume a run
Keeps the SAME run going: one job, one run id, steps and usage add up. A paused run: the agent is told a person had the browser (plus the optional note) and looks at the page again. A run that stopped early (resumable: it used its steps, reached its cost limit, hit too many errors or repeated itself, or its server restarted): it goes on in its session with optional new maxSteps, maxCostUsd and its variables again, and the optional note (shown to the agent as a message). 409 not_resumable for any other run; 409 session_not_running when its session was deleted; 409 run_not_live (or session_ended) when the server running it stopped; the usual plan, spend and rate checks for a run that stopped early.
POST
/v1/agent/runs/{id}/resumeRequest
| Method and path | POST/v1/agent/runs/{id}/resume |
|---|---|
| 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. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
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 |
|---|---|---|---|---|
note | string | – | – | Told to the agent: with the news that a person had the browser (a paused run), or as a message when the run goes on (a run that stopped early). Up to 2000 characters. |
maxSteps | integer | null | – | – | Steps this stretch may take. Default: the run's own maxSteps; null: no step limit. From 1 to 1000. |
maxCostUsd | number | null | – | – | Model cost this stretch may add (usage keeps adding up). Default: the run's own; null: none. From 0.01 to 100. |
variables | object | – | – | The original run's variables again (their values are never stored): every name, as text or {value}. Each keeps the origins and shell rule it had in the original run. |
curl -X POST "https://api.boxline.dev/v1/agent/runs/$RUN_ID/resume" \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"maxSteps": 50, "note": "The download is done; do the upload next."}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst run = await bx.agent.resume("RUN_ID", { maxSteps: 50, note: "The download is done; do the upload next." });const done = await bx.agent.wait(run.id); // the same run, the same idconsole.log(done.status, done.result);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLrun = bx.agent.resume("RUN_ID", max_steps=50, note="The download is done; do the upload next.")done = bx.agent.wait(run["id"]) # the same run, the same idprint(done["status"], done["result"])boxline resume RUN_ID --steps 50 --note "The download is done; do the upload next."Responses
200 OK
The run.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
id | string | – | – | |
status | string | – | running, paused, completed, failed, canceled | |
task | string | – | – | |
sessionId | string | – | – | |
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 | – | – | |
keySource | string | – | project, platform | Whose key a model call uses, the project's own (project, no model charge from Boxline) or the platform's. |
mode | string | tools | tools, computer | tools: the page view and browser tools. computer: the provider's own computer-use tool on screenshots (models with supportsComputerUse; 400 otherwise, or without a browser). |
steps | object[] | – | – | |
steps[].type | string | – | text, tool, handover, resume, captcha, message, code | |
steps[].by | string | – | user, agent, captcha, auto, person | handover: who paused the run; captcha solved: who solved it (auto or person). |
steps[].from | string | – | user | message steps: who wrote it. |
steps[].id | string | – | – | message steps: the message's id (from sendAgentRunMessage). |
steps[].sentAt | string | – | – | message steps: when it was sent (at: when the model received it). Format: date-time. |
steps[].delivered | boolean | – | – | message steps: true (a message is a step once the model has it). |
steps[].at | string | – | – | Format: date-time. |
steps[].text | string | – | – | |
steps[].thought | string | – | – | tool and handover steps: the model's own words that came with the call (what it is doing and what it will do next) and, when the provider gives them in words, its reasoning (OpenAI's reasoning summaries, Claude's thinking), redacted like everything else. Also sent live as a {type:"thought", text, at} event. Up to 2000 characters. |
steps[].name | string | – | – | |
steps[].input | any | – | – | |
steps[].output | string | – | – | |
steps[].isError | boolean | – | – | |
steps[].ms | integer | – | – | |
steps[].n | integer | – | – | The step's number in the run, from 1. Steps are only added, so it never changes. A session event's data.step is this number. At least 1. |
steps[].screen | object | – | – | Browser and computer tool steps: the screen the action led to. When the model got a screenshot the frame is that exact image; otherwise the screen as the action left it. Without a recording (or while the run works with variables) only url and title. |
steps[].screen.frame | integer | – | – | The frame's number in the session's recording. |
steps[].screen.url | string | – | – | |
steps[].screen.title | string | – | – | |
steps[].screen.image | string | – | – | The frame's address (GET /v1/sessions/{id}/recording/frames/{frame}, image/jpeg; it needs the API key like the rest of the API). Format: uri. |
steps[].shell | object | – | – | bash steps. The command's output stays in output, exactly what the model got. |
steps[].shell.exitCode | integer | null | – | – | |
steps[].shell.files | object[] | – | – | Files created or changed in the workspace while the command ran (paths relative to the workspace, by path). Deleted files and changes outside the workspace are not listed. Left out by a machine from before this field. Up to 20 items. |
steps[].shell.files[].path | string | – | – | |
steps[].shell.files[].bytes | integer | – | – | |
steps[].shell.more | integer | – | – | How many more files changed beyond the 20 listed. |
steps[].usage | object | – | – | The model reply this step is the first of (the other steps of the same reply have none). The steps' tokens add up to the run's usage. |
steps[].usage.inputTokens | integer | – | – | |
steps[].usage.outputTokens | integer | – | – | |
steps[].usage.costUsd | number | null | – | – | Worked out like the run's (null for a model that is not priced). |
steps[].state | string | – | solving, waiting, solved, received, timeout | captcha steps: solving (automatic), waiting (a person's turn) or solved; code steps: waiting, received or timeout. |
steps[].kind | string | – | – | captcha steps: the CAPTCHA kind; code steps: code or link. |
steps[].credential | string | – | – | code steps: the password credential whose code or sign-in link the run waits for. |
steps[].host | string | – | – | captcha steps: the host of the page. |
steps[].reason | string | – | – | captcha waiting: why a person is asked. |
result | any | – | – | The final text; with an output schema, the JSON answer (null until it completes). |
resultText | string | null | – | – | The final text; with an output schema, a one-sentence summary of the answer. |
output | object | null | – | – | The run's output schema, or null. |
error | string | null | – | – | |
errorCode | string | null | – | – | max_steps (it used all its steps without finishing; resultText then says what is done and what is left, and resumable until when it can be resumed), max_cost (its maxCostUsd was reached; resumable, no summary), too_many_errors (maxConsecutiveErrors tool errors in a row; resumable), no_progress (the same page-reading or shell call with the same result 5 times in a row; resumable), server_restarted (the API server running it stopped while its session went on; resumable), session_timeout (its session reached its time limit while it worked), session_ended (its session ended another way; error names how), output_invalid (the answer did not match the output schema after the repair try, or the schema was too complex to check it), internal (an error on the platform's side; details only in its logs), or the code of the platform error that stopped the run (e.g. spend_limit, captcha_timeout, handover_timeout). |
resumable | object | null | – | – | Set while the run can be resumed (Resume a run): it stopped early (max_steps, max_cost, too_many_errors, no_progress, server_restarted), its session is running or stopped, until the window passes. |
resumable.until | string | – | – | Format: date-time. |
variableNames | string[] | – | – | The names of the run's own variables (never their values): resumeAgentRun needs the values again. |
maxSteps | integer | null | – | – | The run's step limit; null: none (also shown for runs from before it was kept). |
maxCostUsd | number | null | – | – | The run's money budget (USD of model cost), or null. |
maxConsecutiveErrors | integer | – | – | Tool errors in a row that stop the run. |
sessionExpiresAt | string | null | – | – | The run's session's expiresAt: when its time limit ends it. Format: date-time. |
usage | object | – | – | |
usage.inputTokens | integer | – | – | |
usage.outputTokens | integer | – | – | |
usage.costUsd | number | null | – | – | |
handover | object | null | – | – | Set while paused. |
handover.by | string | – | user, agent, captcha | |
handover.reason | string | null | – | – | |
taskId | string | null | – | – | The task that started this run. |
taskRunId | string | null | – | – | |
createdAt | string | – | – | Format: date-time. |
finishedAt | string | null | – | – | Format: date-time. |
{ "id": "…", "status": "running", "task": "Find the price of the Pro plan on example.com", "sessionId": "…", "provider": "anthropic", "model": "claude-sonnet-5-5", "keySource": "project", "mode": "tools", "steps": [ { "type": "text", "by": "user", "from": "user", "id": "…", "sentAt": "2026-09-29T10:00:00.000Z", "delivered": false, "at": "2026-09-29T10:00:00.000Z", "text": "…", "thought": "…", "name": "Work account", "input": null, "output": "…", "isError": false, "ms": 0, "n": 1, "screen": { "frame": 0, "url": "https://example.com/", "title": "Example Domain", "image": "…" }, "shell": { "exitCode": 0, "files": [ {} ], "more": 0 }, "usage": { "inputTokens": 0, "outputTokens": 0, "costUsd": 0 }, "state": "solving", "kind": "…", "credential": "…", "host": "…", "reason": "…" } ], "result": null, "resultText": "…", "output": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "title", "price" ] }, "error": "…", "errorCode": "…", "resumable": { "until": "2026-09-29T10:00:00.000Z" }, "variableNames": [ "…" ], "maxSteps": 0, "maxCostUsd": 0, "maxConsecutiveErrors": 0, "sessionExpiresAt": "2026-09-29T10:00:00.000Z", "usage": { "inputTokens": 0, "outputTokens": 0, "costUsd": 0 }, "handover": { "by": "user", "reason": "…" }, "taskId": "…", "taskRunId": "…", "createdAt": "2026-09-29T10:00:00.000Z", "finishedAt": "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. |
| 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. |
| 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. |
{ "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.