Scout · Endpoints

Journey

Run a multi-step browser flow in one request — navigate, interact, extract, screenshot, or evaluate — with optional visual debug screenshots per step.

POST/v1/journeyAPI key

Cost: 10 + 2 per step (+15 if any evaluate; +1 per debug screenshot, or +1 reserved when on_error_only).

Concept

A journey keeps one browser context for the whole request: cookies, storage, and navigation state carry across steps. Use it when steps depend on each other (login → click → assert).

	Journey	Jobs
Shape	One target flow, many ordered steps	Many independent operations (often many URLs)
Browser state	Shared (cookies, session) across steps	Each nested request is isolated
Use when	Multi-step path on the same site	Batch screenshots/extracts across a URL list
Endpoint	`POST /v1/journey`	POST /v1/jobs

Do not use a journey to “fan out” unrelated URLs — that is what jobs are for.

Request body

Name	Type	Required	Description
`steps`	`array`	required	Ordered steps (1–40).
`width / height`	`number`	optional	Viewport size (overridden by device presets on other endpoints; journey uses width/height/user_agent).
`user_agent`	`string`	optional	Override UA for the journey context.
`headers`	`object`	optional	Extra HTTP headers for navigations.
`cookies`	`array`	optional	Seed cookies — requires verified domain for sensitive journeys.
`dismiss_cookie_banner`	`boolean`	optional	After each navigate/set_content, best-effort known CMP accept (no domain verify).
`debug`	`boolean \| object`	optional	Attach per-step URL + optional viewport screenshots for authoring.

Step types

Name	Type	Description
`navigate`	`step`	Load url. Optional wait_until, timeout_ms.
`set_content`	`step`	Inject html into the page (isolated content).
`interact`	`step`	click / type / fill / scroll / hover / press_key / select_option / wait / wait_for_selector — verified domain.
`extract`	`step`	Inline fields[] like POST /v1/extract.
`visibility`	`step`	Inline visibility check for selector.
`screenshot`	`step`	Capture viewport/fullpage into step data.base64.
`evaluate`	`step`	Run JS expression — Pro / internal only; verified domain.
`wait_for_function`	`step`	Poll expression until truthy (timeout_ms).

Interact actions

When type is interact, set action plus the fields for that action:

Name	Type	Description
`click`	`action`	Requires selector.
`type`	`action`	selector + text; optional clear.
`fill`	`action`	selector + text (replace value).
`scroll`	`action`	Optional selector or y offset.
`hover`	`action`	Requires selector.
`press_key`	`action`	key (e.g. Enter); optional selector focus.
`select_option`	`action`	selector + value.
`wait`	`action`	ms delay.
`wait_for_selector`	`action`	selector + optional state / timeout_ms.

Domain verify

Sensitive steps

interact, evaluate, and client cookies require verified ownership for every navigate host. Read-only journeys (navigate + extract / visibility / screenshot / wait) do not. dismiss_cookie_banner is allowed without verify (fixed CMP allowlist only).

Visual debug

Set debug: true (or an options object) while authoring journeys. Each step result gains debug.url and usually debug.screenshot.base64 (viewport JPEG). Decode the base64 to preview what the headless browser saw after that step.

Name	Type	Required	Description
`debug`	`true`	optional	Shorthand: screenshots after every step.
`debug.screenshots`	`boolean`	optional	Default true. Set false to only attach debug.url.
`debug.on_error_only`	`boolean`	optional	Only capture a screenshot on the failing step.
`debug.format`	`jpeg \| png`	optional	Default jpeg.
`debug.quality`	`1–100`	optional	JPEG quality (default 72).

json

{
  "debug": { "on_error_only": false, "format": "jpeg", "quality": 72 },
  "steps": [
    { "type": "navigate", "url": "https://example.com" },
    { "type": "interact", "action": "click", "selector": "a.pricing" },
    { "type": "extract", "fields": [{ "name": "h1", "selector": "h1", "type": "text" }] }
  ]
}

bash

# After a debug journey, decode one step shot:
# steps[i].debug.screenshot.base64 → file
echo "$BASE64" | base64 -d > step-2.jpg

Credits & size

Full-step debug screenshots add +1 credit per step and grow the JSON response. Use { "on_error_only": true } once a journey is stable.

Example (login + extract)

bash

curl -X POST https://scout.macrocontent.dev/v1/journey \
  -H "Authorization: Bearer sk_scout_…" \
  -H "Content-Type: application/json" \
  -d @journey.json

json

{
  "steps": [
    { "type": "navigate", "url": "https://example.com/login" },
    { "type": "interact", "action": "fill", "selector": "#email", "text": "demo.user" },
    { "type": "interact", "action": "click", "selector": "button[type=submit]" },
    { "type": "extract", "fields": [{ "name": "welcome", "selector": "h1", "type": "text" }] }
  ]
}

Response shape

json

{
  "status": "success",
  "steps": [
    {
      "index": 0,
      "type": "navigate",
      "ok": true,
      "data": { "url": "https://example.com/" },
      "debug": {
        "url": "https://example.com/",
        "screenshot": { "format": "jpeg", "base64": "…" }
      }
    }
  ],
  "final_url": "https://example.com/",
  "cookies": [],
  "response_time_ms": 1234,
  "debug": {
    "enabled": true,
    "screenshots": true,
    "on_error_only": false,
    "screenshot_count": 1
  },
  "timestamp": "…"
}

HTTP 200 when every step ok; 422 if a step fails (partial steps[] still returned — useful with debug).