Runs

A run is one browser-driven attempt at an account: register, login, or connect. It is the thing you watch after any account call — it holds the status, the reason a human is needed, the live view URL, and the final outcome. Runs are created by POST /v1/registrations, POST /v1/registrations/:id/login, and POST /v1/connections. There is no endpoint that creates a run directly. Observe one by polling GET /v1/runs/:id or by subscribing to the run.blocked / run.completed / run.failed webhooks.

The run object

{
  "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
  "type": "register",
  "status": "blocked",
  "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
  "error": { "code": "CAPTCHA_REQUIRED", "detail": "captcha on the signup form" },
  "result": null,
  "liveViewUrl": "https://app.hyperbrowser.ai/live?...",
  "gatewaySessionId": "3f6a9b2c-...",
  "createdAt": "2026-07-20T11:00:00.000Z",
  "endedAt": null
}

Field	Description
`type`	`register`, `login`, or `connect`.
`status`	See the lifecycle below.
`error`	`{ code, detail? }` — set while `blocked` (why a human is needed) and on `failed` (why it failed). `null` otherwise, and cleared on resume.
`result`	Set on `completed` — the agent’s final answer, e.g. `{ "answer": "STATE: LOGGED_IN" }`. Treat it as diagnostic, not as a stable contract.
`liveViewUrl`	Interactive browser live view: a human can watch and drive. Set once a browser session exists; the takeover surface on a blocked run.
`gatewaySessionId`	The browser session behind the run. Needed for the recording; grants nothing that `liveViewUrl` doesn’t.
`endedAt`	Set when the run reaches `completed` or `failed`.

Lifecycle

queued → running → awaiting_verification → completed
                 ↘ blocked (human needed) ↗
                 ↘ failed

Status	Meaning
`queued`	Waiting for a worker slot. The identity’s browser profile is locked to one run at a time.
`running`	The browser agent is driving the app.
`awaiting_verification`	The app sent a verification email; Sente is watching the account’s own inbox and will type the code or open the link. Times out after 8 minutes → `failed VERIFICATION_TIMEOUT`.
`blocked`	The run needs a human. `error.code` says why; `liveViewUrl` is the interactive takeover surface. Held for 10 minutes, then auto-fails `BLOCKED_TIMEOUT`.
`completed`	Terminal success — the agent confirmed it ended up logged in, and the account is now `active`.
`failed`	Terminal failure; `error.code` says why.

completed and failed are terminal and never change afterwards — an abort that races a completion loses.

Blocked codes

Code	Why the run paused	What clears it
`SUBMIT_CONFIRMATION_REQUIRED`	You passed `confirmBeforeSubmit`: the form is filled and waiting for a person to click the final submit.	Click submit in the live view, then resume. The agent is told not to submit again.
`CAPTCHA_REQUIRED`	The page shows a CAPTCHA. Sente does not attempt CAPTCHAs.	A human completes it in the live view, then resume.
`PHONE_REQUIRED`	The app wants a phone number or an SMS code. Sente has no SMS channel.	A human handles it in the live view, then resume.
`MFA_REQUIRED`	Connected account: a second factor went to the owner’s email or phone, which Sente cannot read.	Enter the code in the live view, then resume. Avoidable for emailed codes via `verifyToIdentity` — see Connections.
`TOTP_REQUIRED`	The app wants an authenticator code and no TOTP seed is vaulted, or three server-side injections were rejected.	Enter a code from your authenticator in the live view, then resume. With a valid vaulted seed this never blocks.
`PAYMENT_REQUIRED`	The flow is asking for payment details. Sente never enters payment data.	A human decides — usually abort.
`MISSING_FIELD`	The form wants something the agent doesn’t have (company name, invite code, …).	Fill it in the live view, then resume.
`LOGIN_UNCONFIRMED`	The agent could not confirm it ended up logged in.	Check the live view, finish the login, then resume.
`MANUAL_INTERVENTION`	You paused the run yourself via `POST /v1/runs/:id/intervene`.	Drive the browser, then resume.

A blocked run is held for 10 minutes and then fails BLOCKED_TIMEOUT — the browser session cannot be parked indefinitely. Subscribe to run.blocked (or run sente watch) rather than discovering the block on your next poll; the webhook payload carries holdExpiresAt so a notification can say how long the human has.

Failure codes

Code	Why the run failed	What to do
`BLOCKED_TIMEOUT`	It blocked and nobody resumed inside the hold.	Retry, and wire up `run.blocked` so someone is paged next time.
`VERIFICATION_TIMEOUT`	No usable verification email arrived within 8 minutes.	Check the app actually mails the identity’s address; check Messages for what did arrive.
`AUTOMATION_STUCK`	The agent could not make progress, its answer was unclassifiable, the run exceeded its wall clock, or its worker died. `detail` carries the agent’s own reason where there is one.	Read `detail` and the recording, then retry.
`APP_UNREACHABLE`	A resource the run depends on disappeared mid-run — its identity or registration was deleted.	Don’t delete identities with live runs; `DELETE /v1/identities/:id` refuses with `IDENTITY_BUSY` for exactly this reason.
`ABORTED`	You aborted it via `POST /v1/runs/:id/abort`.	—

A blocked-style code such as CAPTCHA_REQUIRED can also appear on a failed run. That happens when the browser session had already ended, so takeover was impossible — the code is kept because it is the truthful reason, not because a human could have stepped in.

List runs

GET /v1/runs Every run in your org, newest first — the activity feed behind the dashboard.

Query param	Type	Required	Description
`identityId`	string	no	Only runs for this identity.
`status`	string	no	Exact match (`queued`, `running`, `awaiting_verification`, `blocked`, `completed`, `failed`).
`type`	string	no	Exact match (`register`, `login`, `connect`).
`since`	ISO date	no	Only runs created at or after this timestamp.
`limit`	int 1–200	no	Default 50.

curl "https://api.sente.run/v1/runs?status=blocked&limit=20" \
  -H "Authorization: Bearer sk_sente_..."

Response 200: an array of list rows. A list row is a different, narrower projection than the run object — it joins the identity’s email and the target app, and omits result, liveViewUrl, and gatewaySessionId. Fetch GET /v1/runs/:id for those.

[
  {
    "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
    "type": "register",
    "status": "blocked",
    "error": { "code": "CAPTCHA_REQUIRED", "detail": "captcha on the signup form" },
    "createdAt": "2026-07-20T11:00:00.000Z",
    "endedAt": null,
    "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "identityEmail": "acme-qa@sente.run",
    "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "appUrl": "https://app.example.com/signup"
  }
]

Filter values are not validated. ?status=nope returns [], and an unknown or another org’s identityId also returns [] rather than the 404 that GET /v1/messages gives. An empty array is not evidence that your filter was spelled correctly.

Get a run

GET /v1/runs/:id

curl https://api.sente.run/v1/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6 \
  -H "Authorization: Bearer sk_sente_..."

sente run show run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_KEY! });

// Polls until completed | failed | blocked. `timeout` is MILLISECONDS (default 180000);
// on timeout it returns the last-polled run, so always branch on run.status.
const run = await sente.runs.waitForRun("run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6", {
  timeout: 300_000,
});

if (run.status === "blocked") {
  console.log(`needs a human: ${run.error?.code}`);
  console.log(`live view: ${run.liveViewUrl}`);
  // ...after the person clears the gate:
  await sente.runs.resume(run.id);
} else if (run.status === "failed") {
  console.error(run.error?.code, run.error?.detail);
}

import os
from sente import Sente

sente = Sente(api_key=os.environ["SENTE_API_KEY"])

# Polls until completed | failed | blocked. `timeout` is SECONDS (default 180);
# on timeout it returns the last-polled run, so always branch on run.status.
run = sente.runs.wait_for_run("run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6", timeout=300)

if run.status == "blocked":
    print("needs a human:", (run.error or {}).get("code"))
    print("live view:", run.live_view_url)
    # ...after the person clears the gate:
    sente.runs.resume(run.id)
elif run.status == "failed":
    print("failed:", run.error)

Response 200: the run object. 404 {"error": "not found"} otherwise.

Resume a blocked run

POST /v1/runs/:id/resume Hands control back to the agent after a human cleared the gate in the live view — completed the CAPTCHA, entered the code, clicked submit. The agent re-observes the page and continues from wherever the human left it. No body.

curl -X POST https://api.sente.run/v1/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6/resume \
  -H "Authorization: Bearer sk_sente_..."

Response 200: the run object with "status": "running" and "error": null. Writes a run.resume audit event. 409 {"error": "run is not blocked", "code": "NOT_BLOCKED", "status": "running"} when the run isn’t blocked — the body carries the status it actually has, which is usually the answer to why.

Take over a live run

POST /v1/runs/:id/intervene Pauses a running or awaiting_verification run so a human can drive the browser through the interactive liveViewUrl. The browser session stays alive; POST /:id/resume hands back. No body.

curl -X POST https://api.sente.run/v1/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6/intervene \
  -H "Authorization: Bearer sk_sente_..."

Response 200: the run object with "status": "blocked" and "error": { "code": "MANUAL_INTERVENTION", "detail": "paused for manual takeover" }. Writes a run.intervene audit event. 409 {"error": "run is not intervenable", "code": "NOT_INTERVENABLE", "status": "queued"} when the run isn’t running or awaiting_verification — a queued run has no browser yet, a blocked one is already paused, and a terminal one is done.

A takeover uses the same 10-minute hold as any other block. Walk away without resuming and the run fails BLOCKED_TIMEOUT.

Abort a run

POST /v1/runs/:id/abort Terminates a non-terminal run and stops its browser session. If the run completes at the same moment, the completion wins and you get the 409. No body.

curl -X POST https://api.sente.run/v1/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6/abort \
  -H "Authorization: Bearer sk_sente_..."

Response 200: the run object with "status": "failed" and "error": { "code": "ABORTED", "detail": "aborted by user" }. If the registration was still pending, it is marked failed; an already-active account is untouched. Writes a run.abort audit event. 409 {"error": "run is already terminal", "code": "ALREADY_TERMINAL", "status": "completed"} if it already ended.

An aborted run counts as failed, and failed runs never count against your run quota.

Get the run recording

GET /v1/runs/:id/recording The run’s browser-session video — the fastest way to see what the agent actually did. Ready shortly after the run ends; poll while it processes.

curl https://api.sente.run/v1/runs/run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6/recording \
  -H "Authorization: Bearer sk_sente_..."

{ "status": "completed", "recordingUrl": "https://...mp4" }

`status`	Meaning
`pending` / `in_progress`	Still processing — poll again. `recordingUrl` is `null`.
`completed`	`recordingUrl` is ready.
`failed`	The recording is unavailable — also what you get if the browser layer errors while looking it up.
`not_enabled`	The run never had a browser session, e.g. it failed before one started.

This endpoint returns 200 even when the recording can’t be produced; only an unknown run id gives 404.

What a run is and how the loop works.

Human takeover

The block, the live view, and the resume.

Webhooks

Get pushed the block instead of polling for it.

​The run object

​Lifecycle

​Blocked codes

​Failure codes

​List runs

​Get a run

​Resume a blocked run

​Take over a live run

​Abort a run

​Get the run recording

​Related

Runs

Human takeover

Webhooks

The run object

Lifecycle

Blocked codes

Failure codes

List runs

Get a run

Resume a blocked run

Take over a live run

Abort a run

Get the run recording

Related