Skip to main content
POST
/
v1
/
sessions
/
{id}
/
events
/
wait
Wait for Event
curl --request POST \
  --url https://api.bctrl.ai/v1/sessions/{id}/events/wait \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventTypes": [
    "<string>"
  ],
  "after": "<string>",
  "timeoutMs": 123,
  "pageId": "<string>",
  "contextId": "<string>"
}
'
{
  "event": {
    "id": "<string>",
    "sessionId": "<string>",
    "sessionType": "<string>",
    "eventType": "<string>",
    "eventData": {},
    "createdAt": "<string>"
  },
  "cursor": {},
  "timedOut": true
}
​
id
string
required
Session ID.
​
eventTypes
string[]
Event types to wait for.
​
after
string
Only consider events after this cursor.
​
timeoutMs
number
Maximum wait time in ms. Default: 30000, max: 120000.
​
pageId
string
Filter by page ID in event data.
​
contextId
string
Filter by context ID in event data.

​
Examples

// Wait for a specific navigation event
const response = await fetch(
  `https://api.bctrl.ai/v1/sessions/${sessionId}/events/wait`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      eventTypes: ['page.navigated'],
      timeoutMs: 10000,
    }),
  }
);
const { event, timedOut } = await response.json();

​
Response

​
event
object | null
required
The matched event, or null if timed out.
​
cursor
string | null
required
Cursor at the matched event position.
​
timedOut
boolean
required
true if no matching event was found before timeout.
Response Example
{
  "event": {
    "id": "evt_1",
    "sessionId": "sess_abc123",
    "sessionType": "browser",
    "eventType": "page.navigated",
    "eventData": {
      "url": "https://example.com/dashboard",
      "pageId": "page_1"
    },
    "createdAt": "2025-01-15T10:00:05Z"
  },
  "cursor": "2025-01-15T10:00:05Z|evt_1",
  "timedOut": false
}