AI sessions.

An AI session is an autonomous AI agent that drives a real browser toward a goal you describe — and records the steps that worked into a reusable workflow. It is how a described automation becomes a deterministic one.

Writ runs on your own accounts, with your own credentials and data, on sites you are authorized to use.

model ▸ what it is

Goal in, workflow out.

You give the session a goal and an entry URL. It observes the page, chooses actions, verifies results, and keeps going until the goal is met, a limit is reached, or it is cancelled. What it did is not lost in a transcript: the working steps become an editable workflow you can replay without AI.

This is the “describe” authoring path — Scribe on top of an AI session. The recorded result is ordinary workflow JSON: read it, trim it, re-record parts of it.

request ▸ the fields

Session fields.

A session is created with:

Field	Role
`goal`	What the session should accomplish, in plain words.
`entry_url`	Where the browser starts.
`form_data`	Values the session may use — and the recorded workflow will parameterize on.
`ai_model`	Which model drives the session.
`mode`	How the session behaves toward its goal.
`max_steps`	Cap on recorded steps.
`max_actions`	Cap on actions the agent may take.
`timeout_ms`	Overall time budget for the session.
`headless`	Whether the browser renders a visible window.
`execution_target`	Where the browser runs.
`default_persona_id`	The persona whose saved sign-in state and 2FA the session may use.
`auto_validate`	Re-run the recorded workflow to prove it works; validation_status is pending, passed or failed.

lifecycle ▸ five statuses

Session statuses.

A session reports one of five statuses:

Status	Meaning
`pending`	Created, not yet driving the browser.
`running`	The agent is observing and acting.
`completed`	The goal was reached; results and any recorded workflow are available.
`failed`	The session ended without reaching the goal — the error says why.
`cancelled`	Stopped on request.

telemetry ▸ what it reports

What a session reports.

While it runs — and after it settles — a session exposes exactly what it did and what it cost:

Field	What it tells you
`steps_taken`	How many steps the agent has performed.
`workflows_generated`	How many workflows the session recorded.
`input_tokens / output_tokens / total tokens`	Token usage, split by direction.
`ai_calls_count`	How many model calls the session made.
`credits_consumed / ai_cost_usd`	What the session drew from your included pool, and its USD cost.
`progress_message / current_url`	Live narration: what the agent is doing, and where the browser is.

api ▸ the surface

The API surface.

Sessions are ordinary REST resources:

GET    /api/automation/ai-sessions
POST   /api/automation/ai-sessions
GET    /api/automation/ai-sessions/{id}
GET    /api/automation/ai-sessions/{id}/steps
PATCH  /api/automation/ai-sessions/{id}
DELETE /api/automation/ai-sessions/{id}
POST   /api/automation/ai-sessions/{id}/cancel
POST   /api/automation/ai-sessions/{id}/link-workflow

Running a session requires the workflows:execute scope on the calling key. link-workflow attaches a recorded workflow to the session that produced it.

secrets ▸ the contract

What the model never sees.

Credentials and secrets are masked end to end: the model only ever sees [SECURE:key] markers in what it reads, and emits {{secret:key}} placeholders in what it writes. The real values resolve at dispatch — outside the model, outside the transcript, outside the recorded workflow.

assist ▸ single-shot helpers

Single-shot helpers are not sessions.

Beside sessions, a set of one-shot AI-assist endpoints answer a single request and stop — no browser loop, no recorded workflow:

Helper	What it does
`chat`	One question, one answer, in product context.
`generate-extract`	Draft an extract step for a page.
`build-scraper`	Draft an extraction workflow from a description.
`optimize-workflow`	Suggest a more robust version of an existing workflow — shown as a preview, never a silent rewrite.
`find-selectors`	Propose stable selectors for an element.
`generate-automation`	Draft a trigger/action automation from a description.
`generate-streaming-script`	Write the advanced script for a streaming session.

If you need the browser loop — observe, act, verify, record — that is a session. If you need one artifact generated, that is a helper. Streaming sessions have their own reference: streaming.

billing ▸ flat per-token

How AI is billed.

AI is billed flat and model-blind: $3.20 per 1M tokens, whatever the model — and there is no per-call fee. Sessions draw grant-first from your plan’s included credit pool.

Your plan’s AI token allowance is telemetry — a usage reference, not a separate free band. What a session actually consumed is always visible on the session itself; see billing & usage.

next ▸ where to go

Keep going.

Workflows — what the recorded result is, and how it runs without AI.
Streaming — keep a session-backed browser open and drive it from your own client.
Billing & usage — the credit pool sessions draw from.