> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapengine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Evaluate

> Run an AI prompt against the current page — either a single-shot extraction (simple) or a multi-step browser agent (agent).

## 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`](/api-reference/endpoint/ai-evaluate-stream).

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Browser session ID (UUID).
</ParamField>

## Body

<ParamField body="prompt" type="string" required={true}>
  Natural-language instruction for the model.
</ParamField>

<ParamField body="mode" type="string" default="simple">
  One of `simple`, `agent`.
</ParamField>

<ParamField body="maxSteps" type="integer" default="20">
  For `agent` mode, the maximum number of browser actions the model may take.
</ParamField>

<ParamField body="model" type="string">
  Explicit LLM model ID (e.g. `claude-sonnet-4-20250514`, `gpt-4o`). Defaults to the account's configured default.
</ParamField>

<ParamField body="schema" type="object">
  Optional JSON schema. When supplied, the response `result` is constrained to match.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL (simple extraction) theme={null}
  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"]
      }
    }'
  ```

  ```bash cURL (agent) theme={null}
  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": "Find the cheapest flight from SFO to JFK next Friday and report the price.",
      "mode": "agent",
      "maxSteps": 30
    }'
  ```
</CodeGroup>

## Response

### Success Response (200)

<ResponseField name="success" type="boolean">
  True when the evaluation finished. False when it aborted (see `error`).
</ResponseField>

<ResponseField name="result" type="any">
  Model output. When `schema` was supplied, conforms to that schema.
</ResponseField>

<ResponseField name="error" type="string">
  Error message when `success` is false.
</ResponseField>

<ResponseField name="steps" type="integer">
  Number of browser actions taken (agent mode).
</ResponseField>

<ResponseField name="model" type="string">
  Model ID that was used.
</ResponseField>

<ResponseField name="tokensUsed" type="integer">
  Total tokens consumed by the evaluation.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "success": true,
  "result": { "name": "Widget Pro", "price": 49.99 },
  "model": "claude-sonnet-4-20250514",
  "tokensUsed": 1832
}
```

### Error Responses

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