> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Novita } from 'novita-sandbox'

  const novita = new Novita()
  const result = await novita.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 novita.sandbox.getEvents({
      sandboxID: 'iq721h44siv24wmyrh5oc',
      limit: 10,
      offset: 10,
    })

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

  ```python Python icon="python" theme={"system"}
  from novita_sandbox import Novita

  novita = Novita()

  result = novita.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 = novita.sandbox.get_events(
          sandbox_id="iq721h44siv24wmyrh5oc",
          limit=10,
          offset=10,
      )

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

  ```bash CLI icon="terminal" theme={"system"}
  # List events for a sandbox
  novita-sandbox-cli sandbox events <sandboxID>

  # Filter by event names / state
  novita-sandbox-cli sandbox events <sandboxID> --events create,pause,resume --state success
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Novita } from 'novita-sandbox'

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

  console.log(result.items)
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox import Novita

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

  print(result.items)
  ```
</CodeGroup>

## Filter Events

Use query parameters to narrow the event timeline.

| Option       | Type     | Required | Default / Limit                          | Description                                                                                                                |
| ------------ | -------- | -------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `startTime`  | `int64`  | No       | Defaults to `endTime - 30 days`          | Query start time as a Unix timestamp in seconds. The range is inclusive.                                                   |
| `endTime`    | `int64`  | No       | Defaults to the current time             | Query 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` | No       | Defaults to the key event set            | Comma-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`  | No       | Default `0`, minimum `0`                 | Number of events to skip.                                                                                                  |
| `limit`      | `int32`  | No       | Default `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

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

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

| Field     | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `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.

| Field          | Description                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| `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

```json JSON icon="code" theme={"system"}
{
  "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
}
```