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

# 列出 Environments

> 列出当前账户下的环境，支持游标分页。

`GET /api/v1/cloud/environments`

列出当前账户下的环境，支持游标分页。默认不返回已归档环境。

## 请求头

| 头部              | 必选 | 说明             |
| --------------- | -- | -------------- |
| `Authorization` | 是  | `Bearer <PAT>` |

## 查询参数

| 参数                 | 类型      | 必选 | 默认值     | 说明                                                    |
| ------------------ | ------- | -- | ------- | ----------------------------------------------------- |
| `limit`            | integer | 否  | 20      | 每页返回数量，范围 1-100；超过 100 返回 `400 invalid_request_error` |
| `page`             | string  | 否  | -       | 上一次响应 `next_page` 返回的游标                               |
| `include_archived` | boolean | 否  | `false` | 设为 `true` 时包含已归档环境                                    |
| `created_at[gte]`  | string  | 否  | -       | 仅返回创建时间大于或等于该 RFC 3339 时间戳的环境                         |
| `created_at[lte]`  | string  | 否  | -       | 仅返回创建时间小于或等于该 RFC 3339 时间戳的环境                         |

完整分页规范详见 [分页](/zh/cloud-agents/api/conventions/pagination)。

## 示例请求

```bash theme={null}
curl -s -X GET "https://api.qoder.com/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "env_019e3bb39b6774d8878cd0b9d237574b",
      "type": "environment",
      "name": "doc-test-env",
      "description": "",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": [],
          "allow_package_managers": false,
          "allow_mcp_servers": false
        },
        "packages": {
          "type": "packages",
          "apt": ["curl"],
          "npm": [],
          "pip": []
        }
      },
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-18T15:28:07.017808Z",
      "updated_at": "2026-05-18T15:28:07.017808Z"
    },
    {
      "id": "env_019e2590d33f711fabf42f2857cecd8a",
      "type": "environment",
      "name": "default",
      "description": "",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": [],
          "allow_package_managers": false,
          "allow_mcp_servers": false
        },
        "packages": {
          "type": "packages",
          "apt": [],
          "npm": [],
          "pip": []
        }
      },
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-14T08:18:28.800813Z",
      "updated_at": "2026-05-14T08:18:28.800813Z"
    }
  ],
  "first_id": "env_019e3bb39b6774d8878cd0b9d237574b",
  "has_more": false,
  "last_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "next_page": null
}
```

## 响应字段

| 字段          | 类型                                                                           | 说明                                               |
| ----------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
| `data`      | [Environment 对象](/zh/cloud-agents/api/environments/schemas#environment-对象)数组 | 当前页的 Environment                                 |
| `first_id`  | string                                                                       | 当前页第一条记录的 ID                                     |
| `last_id`   | string                                                                       | 当前页最后一条记录的 ID                                    |
| `has_more`  | boolean                                                                      | 是否还有更多数据可供翻页                                     |
| `next_page` | string\|null                                                                 | 下一页游标。`has_more` 为 true 时等于 `last_id`，否则为 `null` |

## 错误码

| HTTP | type                    | 说明                                                   |
| ---- | ----------------------- | ---------------------------------------------------- |
| 400  | `invalid_request_error` | `limit` 不是正整数                                        |
| 400  | `invalid_request_error` | 分页游标非法                                               |
| 400  | `invalid_request_error` | `created_at[gte]` 或 `created_at[lte]` 不是 RFC 3339 时间 |
| 401  | `authentication_error`  | 认证失败，PAT 无效或过期                                       |
| 403  | `permission_error`      | 无权访问此资源                                              |

## 注意事项

* 默认按 ID 降序排列
* 已归档的 Environment 不会出现在默认列表中；传 `include_archived=true` 可包含已归档 Environment
* 使用游标分页，不支持 offset 方式

## 相关

<CardGroup cols={2}>
  <Card title="云端环境" icon="server" href="/zh/cloud-agents/environments">
    选择 Agent 运行的容器、网络与依赖。
  </Card>
</CardGroup>