Skip to main content
POST
/
browser
/
sessions
/
{id}
/
tasks
Run Task
curl --request POST \
  --url https://api.example.com/browser/sessions/{id}/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "waitUntil": "<string>",
  "actions": [
    {}
  ],
  "screenshot": {},
  "pdf": {},
  "content": true,
  "filename": "<string>",
  "credentialId": "<string>",
  "mode": "<string>",
  "selectors": {},
  "success": {},
  "pauseTimeoutMs": 123
}
'
{
  "url": "<string>",
  "screenshot": "<string>",
  "pdf": "<string>",
  "content": {},
  "actionResults": [
    {}
  ]
}

​
Overview

The task runner is the workhorse of the Browser Session API. A single request can:
  1. Navigate to a url (optional)
  2. Execute a sequential list of actions against the active page
  3. Capture output artifacts — screenshot, pdf, and/or content — at the end
Actions run in order. If any action fails, the task aborts and the error is returned. Use this endpoint for multi-step flows (login → search → extract) that would otherwise require multiple round trips.

​
Path Parameters

​
id
string
required
Browser session ID (UUID).

​
Body

​
url
string
Optional URL to navigate to before running actions.
​
waitUntil
string
default:"load"
Wait condition for the initial navigation. One of domcontentloaded, load, networkidle.
​
actions
object[]
Sequential list of actions to execute. See Action schema below.
​
screenshot
object
When present, a screenshot is taken after all actions complete. Supports { fullPage?: boolean, selector?: string }.
​
pdf
object
When present, renders a PDF after all actions complete. Accepts the same options as POST /browser/sessions/{id}/pdf (format, landscape, margin, etc.). Returned base64-encoded.
​
content
boolean
When true, returns { html, url } of the final page in the response.

​
Action schema

Every action has a type field. The remaining fields depend on the type.
TypeRequired fieldsOptional fields
navigateurlwaitUntil
clickselector or coordinates—
typeselector, text—
presskeyselector
scrollone of selector / coordinates / text—
waitselector or text—
evaluatescript—
screenshot—selector
uploadFileselector, filename—
authenticatemode + matching fieldscredentialId, selectors, success, pauseTimeoutMs
selectselector, text—
hoverselector—
Key per-field notes:
​
filename
string
For uploadFile: must match a filename previously uploaded via POST /browser/sessions/{id}/files.
​
credentialId
string
For authenticate when mode is vault or vault_then_prompt: UUID of a credential from POST /browser/credentials. Never pass raw username/password.
​
mode
string
For authenticate: one of vault, prompt_user, vault_then_prompt.
​
selectors
object
For authenticate: { username, password, submit?, totp? } — CSS selectors pointing at each login form field.
​
success
object
For authenticate: how to detect login success. { condition: "url" | "selector" | "text" | "networkIdle", value: string, timeoutMs?: integer }.
​
pauseTimeoutMs
integer
default:"300000"
For authenticate with mode: prompt_user: max time to wait for the end-user to complete login via the live view.

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/tasks" \
  -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "waitUntil": "load",
    "actions": [
      { "type": "click", "selector": "a[href=\"/login\"]" },
      { "type": "type", "selector": "#email", "text": "[email protected]" },
      { "type": "type", "selector": "#password", "text": "hunter2" },
      { "type": "click", "selector": "button[type=submit]" },
      { "type": "wait", "selector": "#dashboard" }
    ],
    "screenshot": { "fullPage": true },
    "content": true
  }'

​
Response

​
Success Response (201)

​
url
string
Effective URL of the active tab after all actions.
​
screenshot
string
Base64-encoded PNG, present when the request included screenshot.
​
pdf
string
Base64-encoded PDF bytes, present when the request included pdf.
​
content
object
{ html, url }, present when the request had content: true.
​
actionResults
object[]
One entry per action, in order. Shape depends on the action type (e.g. evaluate returns { value }, authenticate returns { success, reason }).
Example Response: 
{
  "url": "https://app.example.com/dashboard",
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",
  "content": {
    "url": "https://app.example.com/dashboard",
    "html": "<!doctype html>..."
  },
  "actionResults": [
    { "type": "click", "ok": true },
    { "type": "type", "ok": true, "charactersTyped": 18 },
    { "type": "authenticate", "ok": true, "reason": "success" }
  ]
}

​
Error Responses

StatusDescription
400Invalid body — unknown action type, missing required fields for an action, or conflicting parameters.
401Unauthorized — invalid or missing API key.
404Session not found, or a selector inside an action matched nothing.
408An action timed out (e.g. wait selector did not appear, authenticate success condition not met).
422Action failed semantically (e.g. authenticate with mode: vault and domain_mismatch).
503The browser session is temporarily unreachable.

​
Notes

  • Actions run sequentially. Order matters — put wait between flaky interactions.
  • screenshot, pdf, and content are all independent and can be combined in a single task.
  • For long-running login flows, prefer authenticate over scripted type/click pairs — it handles common anti-bot consent banners and supports vault-stored credentials.
  • filename in uploadFile must be uploaded first via POST /browser/sessions/{id}/files.