Skip to main content
POST
/
v1
/
sessions
/
{id}
/
act
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.act('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {
  input: 'Click the login button',
});

console.log(response.data);
{
  "success": true,
  "data": {
    "result": {
      "success": true,
      "message": "Successfully clicked the login button",
      "actionDescription": "Clicked button with text 'Login'",
      "actions": [
        {
          "selector": "[data-testid='submit-button']",
          "description": "Click the submit button",
          "backendNodeId": 123,
          "method": "click",
          "arguments": [
            "Hello World"
          ]
        }
      ]
    },
    "actionId": "<string>"
  }
}

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
input
required

Natural language instruction or Action object

Example:

"Click the login button"

options
object
frameId
string

Target frame ID for the action

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