Runs

Run a task or a capability

Routes the task to the best capability (or runs the one named), fills its inputs and replays the site's API. Answers with the run: succeeded with a verified result, input_required with requirements to answer (POST /api/v1/runs/{runId}/responses), or failed with an error.

With egress: "client" the site requests are sent by you, from your own IP: the answer is egress_required with the next request(s) to send (method, URL, headers, body, and a ready curl). Send each one and post the raw response to /api/v1/egress/{egressId}; Unbrowse reads it and answers with the next request, or the finished run. Unbrowse decides every request and reads every response; it never contacts the site itself in such a run (no cloud browser, no proxy).

post/api/v1/runs

Request

  • Base URL: https://unbrowse.ai
  • URL: https://unbrowse.ai/api/v1/runs
  • Auth: one of:
    • OAuth 2 (authorization code, authorization URL https://unbrowse.ai/authorize, token URL https://unbrowse.ai/oauth/token, scopes: unbrowse)
    • HTTP bearer

Query parameters

deadlineMsinteger

Same as the x-unbrowse-deadline-ms header (the header wins).

Headers

x-unbrowse-deadline-msinteger

Answer within this many ms (clamped to 5,000–300,000; default 60,000). Past it the answer is 504 run_timeout; the run keeps going.

Request body

taskstring

What to do, in plain words. Unbrowse picks the capability.

capabilitystring

A capability id to run instead of routing the task (from /api/v1/capabilities/search).

targetUrlstring uri

The site to do it on, when the task does not name one.

inputobject

The capability's inputs.

accountRefsstring[]

Which kept logins to use.

interactionMode'interactive' | 'unattended' | 'external_handler'

unattended: a check nobody can clear fails instead of waiting.

idempotencyKeystring required

Repeat a request with the same key to get the same run.

deadlineMsinteger

Answer within this many ms; past it 504 run_timeout with a runId to poll (the run keeps going). The x-unbrowse-deadline-ms header wins.

egress'server' | 'client'

client: you send the site requests from your own IP (see /api/v1/egress/{egressId}).

selectstring[]

Keep only these parts of the result. Dots walk keys, [] maps over a list, [n] takes one item, a final {a,b} keeps several keys. Applied to the answer after the run is verified; billing is the same. Paths that matched nothing come back in selectMissing; a malformed path is a 400 invalid_input naming it. Results over 40,000 characters are shortened (truncated), so select what you need.

Example request

{
  "select": [
    "results[].{id,title,price}",
    "total"
  ]
}

Response

The run

runIdstring required
status'accepted' | 'working' | 'input_required' | 'succeeded' | 'failed' | 'outcome_unknown' | 'cancelled' | 'expired' required
capabilityIdstring nullable
phasestring
stateRevisioninteger
resultunknown
requirementsObject[]

What the run needs (status input_required).

errorObject
verifiedboolean

Changes

No recorded changes to this operation across all 1 revision of this API.