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": {}
}
'import requests
url = "https://api.example.com/browser/sessions/{id}/ai/evaluate"
payload = {
"prompt": "<string>",
"mode": "<string>",
"maxSteps": 123,
"model": "<string>",
"schema": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: '<string>',
mode: '<string>',
maxSteps: 123,
model: '<string>',
schema: {}
})
};
fetch('https://api.example.com/browser/sessions/{id}/ai/evaluate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/browser/sessions/{id}/ai/evaluate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => '<string>',
'mode' => '<string>',
'maxSteps' => 123,
'model' => '<string>',
'schema' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/browser/sessions/{id}/ai/evaluate"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/browser/sessions/{id}/ai/evaluate")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/browser/sessions/{id}/ai/evaluate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": "<any>",
"error": "<string>",
"steps": 123,
"model": "<string>",
"tokensUsed": 123
}AI
AI Evaluate
Run an AI prompt against the current page — either a single-shot extraction (simple) or a multi-step browser agent (agent).
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": {}
}
'import requests
url = "https://api.example.com/browser/sessions/{id}/ai/evaluate"
payload = {
"prompt": "<string>",
"mode": "<string>",
"maxSteps": 123,
"model": "<string>",
"schema": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: '<string>',
mode: '<string>',
maxSteps: 123,
model: '<string>',
schema: {}
})
};
fetch('https://api.example.com/browser/sessions/{id}/ai/evaluate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/browser/sessions/{id}/ai/evaluate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => '<string>',
'mode' => '<string>',
'maxSteps' => 123,
'model' => '<string>',
'schema' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/browser/sessions/{id}/ai/evaluate"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/browser/sessions/{id}/ai/evaluate")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/browser/sessions/{id}/ai/evaluate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"<string>\",\n \"mode\": \"<string>\",\n \"maxSteps\": 123,\n \"model\": \"<string>\",\n \"schema\": {}\n}"
response = http.request(request)
puts response.read_body{
"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 tomaxStepsiterations.
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
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"]
}
}'
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
}'
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.
{
"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. |
Was this page helpful?