Skip to main content
POST
/
browser
/
sessions
/
{id}
/
ai
/
evaluate
AI Evaluate
curl --request POST \
  --url https://api.example.com/browser/sessions/{id}/ai/evaluate \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "mode": "<string>",
  "maxSteps": 123,
  "model": "<string>",
  "schema": {}
}
'
{
  "success": true,
  "result": "<any>",
  "error": "<string>",
  "steps": 123,
  "model": "<string>",
  "tokensUsed": 123
}

​
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

​
id
string
required
Browser session ID (UUID).

​
Body

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

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/ai/evaluate" \
  -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract the product name and price from this page.",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" }
      },
      "required": ["name", "price"]
    }
  }'

​
Response

​
Success Response (200)

​
success
boolean
True when the evaluation finished. False when it aborted (see error).
​
result
any
Model output. When schema was supplied, conforms to that schema.
​
error
string
Error message when success is false.
​
steps
integer
Number of browser actions taken (agent mode).
​
model
string
Model ID that was used.
​
tokensUsed
integer
Total tokens consumed by the evaluation.
Example Response: 
{
  "success": true,
  "result": { "name": "Widget Pro", "price": 49.99 },
  "model": "claude-sonnet-4-20250514",
  "tokensUsed": 1832
}

​
Error Responses

StatusDescription
400Invalid body — missing prompt, unknown mode, or malformed schema.
401Unauthorized — invalid or missing API key.
404Session not found or not owned by the caller.
503The model provider or browser session is temporarily unreachable.