Skip to main content
POST
/
v1
/
sessions
/
{id}
/
agentExecute
JavaScript
import Stagehand from 'stagehand-sdk';

const client = new Stagehand({
  browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
  browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
  modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
});

const response = await client.sessions.execute('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {
  agentConfig: {},
  executeOptions: {
    instruction: "Log in with username 'demo' and password 'test123', then navigate to settings",
  },
});

console.log(response.data);
{
  "success": true,
  "data": {
    "result": {
      "success": true,
      "message": "Successfully logged in and navigated to dashboard",
      "actions": [
        {
          "type": "click",
          "reasoning": "<string>",
          "taskCompleted": true,
          "action": "<string>",
          "timeMs": 123,
          "pageText": "<string>",
          "pageUrl": "<string>",
          "instruction": "<string>"
        }
      ],
      "completed": true,
      "metadata": {},
      "usage": {
        "input_tokens": 1500,
        "output_tokens": 250,
        "inference_time_ms": 2500,
        "reasoning_tokens": 123,
        "cached_input_tokens": 123
      }
    }
  }
}

Authorizations

x-bb-api-key
string
header
required

Browserbase API key for authentication

x-bb-project-id
string
header
required

Browserbase project ID

x-model-api-key
string
header
required

API key for the AI model provider (OpenAI, Anthropic, etc.)

Headers

x-stream-response
enum<string>

Whether to stream the response via SSE

Available options:
true,
false
Example:

"true"

x-sent-at
string<date-time>

ISO timestamp when request was sent

Example:

"2025-01-15T10:30:00Z"

Path Parameters

id
string
required

Unique session identifier

Example:

"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"

Body

application/json
agentConfig
object
required
executeOptions
object
required
frameId
string

Target frame ID for the agent

streamResponse
boolean

Whether to stream the response via SSE

Example:

true

Response

200 - application/json

Default Response

success
boolean
required

Indicates whether the request was successful

data
object
required