Sandbox work and access

List boat events

Return Sandbox work, lifecycle, and progress events so product UIs can show what the sandbox is doing. A Sandbox runs many conversations in parallel; this streams all of them by default and every event carries a conversationId. Filter to one or more with conversation. Event payloads are extensible. Clients can long-poll this endpoint with sort=asc and a cursor to stream responses. Response events expose agent text, streaming partials via data.is_streaming, and tool calls/results via data.tools.

GET

sandboxes

{sandboxId}

events

List boat events

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/events \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/events', 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://boat.dev/api/v1/sandboxes/{sandboxId}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://boat.dev/api/v1/sandboxes/{sandboxId}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "type": "events.list",
  "id": "bx_23456789",
  "events": [
    {
      "id": "prompt_123",
      "type": "prompt",
      "timestamp": 1780347055370,
      "taskId": "prompt_123",
      "data": {
        "prompt": "Run tests and summarize failures.",
        "status": "running",
        "is_reverted": false
      }
    },
    {
      "id": "response_123-tools",
      "type": "response",
      "timestamp": 1780347063427,
      "taskId": "prompt_123",
      "data": {
        "content": "",
        "model": "gpt-5.4",
        "tools": [
          {
            "use": {
              "id": "call_123",
              "type": "tool_use",
              "name": "Bash",
              "input": {
                "command": "npm test"
              }
            },
            "result": {
              "type": "tool_result",
              "tool_use_id": "call_123",
              "is_error": false,
              "content": "{\"exitCode\":0}"
            }
          }
        ],
        "is_reverted": false
      }
    },
    {
      "id": "response_123",
      "type": "response",
      "timestamp": 1780347065650,
      "taskId": "prompt_123",
      "data": {
        "content": "Tests passed.",
        "model": "gpt-5.4",
        "is_reverted": false
      }
    }
  ],
  "pageInfo": {
    "nextCursor": null,
    "hasMore": false,
    "limit": 100
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Path Parameters

sandboxId

string

required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Query Parameters

limit

integer

default:100

Maximum items to return.

Required range: 1 <= x <= 200

cursor

string | null

Opaque pagination cursor returned as pageInfo.nextCursor.

sort

enum<string>

default:desc

Sort direction for cursor pagination.

Available options:

asc,

desc

type

string

Comma-separated event type filter, for example prompt,response,steer.

conversation

string

Only return events for this conversation id. Repeat the parameter (or comma-separate) for several. Omit to stream every conversation on the sandbox. See Integrated agents.

Response

The agent's work on the sandbox (prompts, responses), not sandbox lifecycle. A sandbox that was never prompted returns an empty list even though it started, stopped and resumed.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Allowed value: "events.list"

string

required

events

object[]

required

Sandbox work and lifecycle event objects. Event shapes are intentionally extensible; branch on each event type when present.

Show child attributes

pageInfo

object

Show child attributes

List boat events

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/events \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/events', 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://boat.dev/api/v1/sandboxes/{sandboxId}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://boat.dev/api/v1/sandboxes/{sandboxId}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "type": "events.list",
  "id": "bx_23456789",
  "events": [
    {
      "id": "prompt_123",
      "type": "prompt",
      "timestamp": 1780347055370,
      "taskId": "prompt_123",
      "data": {
        "prompt": "Run tests and summarize failures.",
        "status": "running",
        "is_reverted": false
      }
    },
    {
      "id": "response_123-tools",
      "type": "response",
      "timestamp": 1780347063427,
      "taskId": "prompt_123",
      "data": {
        "content": "",
        "model": "gpt-5.4",
        "tools": [
          {
            "use": {
              "id": "call_123",
              "type": "tool_use",
              "name": "Bash",
              "input": {
                "command": "npm test"
              }
            },
            "result": {
              "type": "tool_result",
              "tool_use_id": "call_123",
              "is_error": false,
              "content": "{\"exitCode\":0}"
            }
          }
        ],
        "is_reverted": false
      }
    },
    {
      "id": "response_123",
      "type": "response",
      "timestamp": 1780347065650,
      "taskId": "prompt_123",
      "data": {
        "content": "Tests passed.",
        "model": "gpt-5.4",
        "is_reverted": false
      }
    }
  ],
  "pageInfo": {
    "nextCursor": null,
    "hasMore": false,
    "limit": 100
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}