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

# 沙箱事件

本节介绍如何查询沙箱生命周期中的关键事件，适用于问题排查、审计、用量分析和账单核对等场景。

## 查询沙箱事件

通过 Events API 可以获取当前账号下的沙箱事件列表，并按沙箱、模板、事件类型、状态和时间范围等条件过滤结果。

### 使用 SDK 查询事件

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'

  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)
  }
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter 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)
  ```
</CodeGroup>

### 查询单个沙箱实例的事件

如果您已经创建了一个沙箱，可以直接通过该沙箱对象查询它的事件记录。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'

  const sandbox = await 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={null}
  from ppio_sandbox.code_interpreter import Sandbox

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

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

## 筛选事件

使用查询参数缩小事件时间线范围。

| 参数 | 类型 | 是否必填 | 默认值 / 限制 | 说明 |
| - | - | - | - | - |
| `startTime` | `int64` | 否 | 默认为 `endTime - 30 days` | 查询开始时间，秒级 Unix 时间戳。查询范围包含该时间点。 |
| `endTime` | `int64` | 否 | 默认为当前时间 | 查询结束时间，秒级 Unix 时间戳。必须大于 `startTime`。 |
| `sandboxID` | `string` | 否 | - | 按沙箱 ID 筛选。支持模糊匹配。 |
| `templateID` | `string` | 否 | - | 按模板 ID 筛选。支持模糊匹配。 |
| `events` | `string` | 否 | 默认为关键事件集合 | 逗号分隔的事件类型。当前关键事件集合包括 `create`、`pause`、`resume`、`connect`、`timeout` 和 `delete`。 |
| `state` | `string` | 否 | - | 按事件状态筛选，例如 `success` 或失败状态。 |
| `orderAsc` | `bool` | 否 | `false` | 是否按 `recordAt` 升序排序。默认按降序返回事件。 |
| `offset` | `int32` | 否 | 默认 `0`，最小值 `0` | 跳过的事件数量。 |
| `limit` | `int32` | 否 | 默认 `10`，最小值 `1`，最大值 `100` | 本次最多返回的事件数量。 |

<Note>
  时间字段使用秒级 Unix 时间戳，请勿传入毫秒级时间戳。

  单次查询最大时间范围为 60 天。如需查询更长时间线，请拆分为多个较小时间范围。
</Note>

## 分页

Events API 使用基于 `offset` 的分页方式。首次请求从 `offset: 0` 开始；如果 `hasMore` 为 `true`，下一页使用 `offset + limit` 继续请求。`limit` 最大值为 100。

## 响应字段

事件响应包含 `items` 数组和分页元数据。

| 字段 | 说明 |
| - | - |
| `items` | 符合查询条件的沙箱事件列表。 |
| `total` | 分页前符合查询条件的事件总数。 |
| `hasMore` | 当前页之后是否还有更多事件。 |

`items` 中每个事件对象包含以下字段。

| 字段 | 说明 |
| - | - |
| `eventID` | 唯一事件 ID。 |
| `recordAt` | 事件记录时间，秒级 Unix 时间戳。 |
| `templateID` | 沙箱使用的模板 ID。 |
| `templateName` | 沙箱使用的模板名称。 |
| `sandboxID` | 沙箱 ID。 |
| `eventName` | 事件类型，例如 `create`、`pause`、`resume`、`connect`、`timeout` 或 `delete`。 |
| `state` | 事件状态。 |
| `errorMsg` | 事件失败或发生异常时的错误信息。无错误时通常为空。 |
| `statusCode` | 与操作相关的 HTTP 状态码，如可用。 |

## 响应示例

```json theme={null}
{
  "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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.