List session events
Oldest first. Pass nextAfter back as after to page forward and to poll for new events.
GET
/v1/sessions/{id}/eventsRequest
| Method and path | GET/v1/sessions/{id}/events |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
Query parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
types | string | – | – | Comma-separated event types. |
runId | string | – | – | Only the events an agent run caused in this session (those whose data.runId is this run id). |
after | string | – | – | Only events after this seq (or the previous page's next). |
limit | integer | 500 | – | From 1 to 2000. |
curl "https://api.boxline.dev/v1/sessions/$SESSION_ID/events?types=exec,error" \ -H "x-api-key: $BOXLINE_API_KEY"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst page = await bx.sessions.events("SESSION_ID", { types: ["exec", "error"] });for (const e of page.data) console.log(e.seq, e.type, e.data?.by, e.text);console.log("poll again after", page.nextAfter);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLpage = bx.sessions.events("SESSION_ID", types=["exec", "error"])for e in page.data: print(e["seq"], e["type"], (e.get("data") or {}).get("by"), e.get("text"))print("poll again after", page.next_after)Responses
200 OK
A page of events.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
data | object[] | – | – | |
data[].seq | integer | – | – | |
data[].at | string | – | – | Format: date-time. |
data[].type | string | – | console, network, navigation, error, lifecycle, action, exec, files, captcha | |
data[].level | string | – | – | |
data[].text | string | – | – | |
data[].url | string | – | – | |
data[].method | string | – | – | |
data[].status | integer | – | – | |
data[].resourceType | string | – | – | |
data[].durationMs | integer | – | – | |
data[].tabId | string | – | – | |
data[].data | object | – | – | What the event carries; see ExecEventData (exec), ActionEventData (action) and FilesEventData (files). |
data[].data.by | string | – | api | |
data[].data.runId | string | – | – | The agent run (by: agent). |
data[].data.exitCode | integer | null | – | – | |
data[].data.timedOut | boolean | – | – | |
data[].data.step | integer | – | – | The run's step number (by: agent); the step's n. |
data[].data.files | string[] | – | – | by: agent: the paths (relative to the workspace) of the files the command created or changed, as on the step's shell (at most 20). |
data[].data.credentials | string[] | – | – | The names of the credentials the command was given (never their values). |
data[].data.action | string | – | – | The action name (click, goto, step, …). |
data[].data.line | integer | – | – | by: script: the line of your script that made the call, in the editor's numbers. From 1 to 100000. |
data[].data.frame | integer | – | – | by: agent, with a recording: the recording frame the step ended on (the step's screen.frame). |
data[].data.code | string | – | – | A failure's API error code, when it has one (e.g. provider_unavailable, feature_not_in_plan). |
data[].data.op | string | – | write, delete | |
data[].data.path | string | – | – | Relative to the workspace. |
data[].data.bytes | integer | – | – | op: write: the file's size. |
nextAfter | integer | – | – | The last seq returned (or after when none). |
next | string | null | – | – | Pass it back as after for the next page; null on the last page. |
{ "data": [ { "seq": 0, "at": "2026-09-29T10:00:00.000Z", "type": "console", "level": "…", "text": "…", "url": "https://example.com/", "method": "…", "status": 0, "resourceType": "…", "durationMs": 0, "tabId": "…", "data": { "by": "api", "runId": "…", "exitCode": 0, "timedOut": false, "step": 0, "files": [ "…" ], "credentials": [ "…" ] } } ], "nextAfter": 0, "next": "eyJvIjoiY3JlYXRlZF9kZXNjIiwidCI6IjIwMjYtMDktMjlUMTA6MDA6MDAuMTIzNDU2WiIsImkiOiI2YzFmIn0"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.