云主机列表

GET/v2/instances

按名称、状态、标签与可用区筛选实例。

Bearer Token instances:read 300 次 / 分钟 api.demo.acme-cloud.dev

请求参数

共 7 项

page 可选查询

integer · 默认 1

页码，从 1 开始

page_size 可选查询

integer · 默认 20

每页条数，1–100

sort 可选查询

string

排序字段，前缀 - 表示降序

region 可选查询

string

地域

可选值ap-east-1ap-southeast-1

zone 可选查询

string

可用区

status 可选查询

string

运行状态

可选值runningstoppedstartingstoppingerror

label 可选查询

string

标签过滤，格式 key:value，多个以逗号分隔

响应

3 种状态

200 OK

响应示例

{
  "total": 7,
  "items": [
    {
      "id": "ins_4f21b8",
      "name": "web-01",
      "status": "running",
      "region": "ap-east-1",
      "zone": "ap-east-1a",
      "spec": {
        "cpu": 4,
        "memory_gb": 8,
        "disk_gb": 80
      },
      "public_ip": "43.129.xx.xx",
      "private_ip": "10.2.4.11",
      "image": "ubuntu-26.04-lts",
      "labels": {
        "env": "prod",
        "role": "web"
      },
      "created_at": "2026-06-02T02:14:00Z"
    }
  ]
}

代码示例

cURL

curl -i -X GET 'https://api.demo.acme-cloud.dev/v2/instances?page=1&page_size=20&sort=-created_at&region=ap-east-1&zone=ap-east-1a&status=running&label=env%3Aprod' \
  -H 'Accept: application/json'