# Sandbox Events - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/sandbox-events

# Sandbox Events

Sandbox events provide a queryable timeline of key sandbox lifecycle operations. You can use events for troubleshooting, auditing, usage analysis, and billing reconciliation.

##

[​](#query-sandbox-events)

Query Sandbox Events

Use the events API to list sandbox events for your account. You can filter events by sandbox, template, event type, status, and time range.

###

[​](#query-events-using-the-sdks)

Query events using the SDKs

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox'

const result = await Sandbox.getEvents({
sandboxID: 'iq721h44siv24wmyrh5oc',
events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
limit: 10,
offset: 0,
})

console.log('Events:', result.items)

if (result.hasMore) {
const nextPage = await Sandbox.getEvents({
sandboxID: 'iq721h44siv24wmyrh5oc',
limit: 10,
offset: 10,
})

console.log('Next page:', nextPage.items)
}
```

```
from novita_sandbox.core import Sandbox

result = Sandbox.get_events(
sandbox_id="iq721h44siv24wmyrh5oc",
events=["create", "pause", "resume", "connect", "timeout", "delete"],
limit=10,
offset=0,
)

print("Events:", result.items)

if result.has_more:
next_page = Sandbox.get_events(
sandbox_id="iq721h44siv24wmyrh5oc",
limit=10,
offset=10,
)

print("Next page:", next_page.items)
```

###

[​](#query-events-for-a-sandbox-instance)

Query events for a sandbox instance

If you already have a sandbox instance, use the instance-level events method to query events for that sandbox.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox'

const sandbox = await Sandbox.create()
const result = await sandbox.getEvents({
events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
limit: 10,
})

console.log(result.items)
```

```
from novita_sandbox.core import Sandbox

sandbox = Sandbox.create()
result = sandbox.get_events(
events=["create", "pause", "resume", "connect", "timeout", "delete"],
limit=10,
)

print(result.items)
```

##

[​](#filter-events)

Filter Events

Use query parameters to narrow the event timeline.

OptionTypeRequiredDefault / LimitDescription`startTime``int64`NoDefaults to `endTime - 30 days`Query start time as a Unix timestamp in seconds. The range is inclusive.`endTime``int64`NoDefaults to the current timeQuery end time as a Unix timestamp in seconds. Must be greater than `startTime`.`sandboxID``string`No-Filter by sandbox ID. Partial matching is supported.`templateID``string`No-Filter by template ID. Partial matching is supported.`events``string`NoDefaults to the key event setComma-separated event types. The current key event set is `create`, `pause`, `resume`, `connect`, `timeout`, and `delete`.`state``string`No-Filter by event status, such as `success` or a failure status.`orderAsc``bool`No`false`Sort events by `recordAt` in ascending order. By default, events are returned in descending order.`offset``int32`NoDefault `0`, minimum `0`Number of events to skip.`limit``int32`NoDefault `10`, minimum `1`, maximum `100`Maximum number of events to return.

Time fields use Unix timestamps in seconds. Do not pass millisecond timestamps.The maximum query time range is 60 days. For longer timelines, split requests into multiple smaller time ranges.

##

[​](#pagination)

Pagination

Events use offset-based pagination. Start with `offset: 0`; if `hasMore` is `true`, request the next page with `offset + limit`. The maximum `limit` is 100.

##

[​](#response-fields)

Response Fields

The events response includes an `items` array and pagination metadata.

FieldDescription`items`List of sandbox events that match the query.`total`Total number of events that match the query, before pagination.`hasMore`Whether more events are available after the current page.

Each item in `items` has the following fields.

FieldDescription`eventID`Unique event ID.`recordAt`Event record time as a Unix timestamp in seconds.`templateID`Template ID used by the sandbox.`templateName`Template name used by the sandbox.`sandboxID`Sandbox ID.`eventName`Event type, such as `create`, `pause`, `resume`, `connect`, `timeout`, or `delete`.`state`Event status.`errorMsg`Error message when the event failed or encountered an exception. Usually empty when there is no error.`statusCode`HTTP status code associated with the operation, when available.

##

[​](#example-response)

Example Response

```
{
"items": [
{
"eventID": "evt_123",
"recordAt": 1766650000,
"templateID": "tmpl_abc",
"templateName": "ubuntu-base",
"sandboxID": "i3vrzzatkxojecvfuesnz",
"eventName": "create",
"state": "success",
"errorMsg": "",
"statusCode": 200
}
],
"total": 1,
"hasMore": false
}
```

Last modified on July 1, 2026