Skip to main content
POST
AI Evaluate

Overview

Runs an LLM-driven evaluation against the session’s active page. Two modes:
  • simple — one-shot: the current page’s DOM + screenshot are sent to the model, which answers the prompt (optionally against a JSON schema).
  • agent — multi-step: the model can drive the browser, clicking and navigating for up to maxSteps iterations.
For streaming output, use POST /browser/sessions/{id}/ai/evaluate/stream.

Path Parameters

string
required
Browser session ID (UUID).

Body

string
required
Natural-language instruction for the model.
string
default:"simple"
One of simple, agent.
integer
default:"20"
For agent mode, the maximum number of browser actions the model may take.
string
Explicit LLM model ID (e.g. claude-sonnet-4-20250514, gpt-4o). Defaults to the account’s configured default.
object
Optional JSON schema. When supplied, the response result is constrained to match.

Example Request

Response

Success Response (200)

boolean
True when the evaluation finished. False when it aborted (see error).
any
Model output. When schema was supplied, conforms to that schema.
string
Error message when success is false.
integer
Number of browser actions taken (agent mode).
string
Model ID that was used.
integer
Total tokens consumed by the evaluation.
Example Response:

Error Responses