分页查询用户

GET/v2/users

按关键字、状态、角色组合筛选用户，游标分页。

列表接口统一采用「页码 + 总数字段」的浅分页。当 page * page_size > 10000 时请改用 created_at 游标做深分页，避免大偏移扫描。

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

请求参数

共 8 项

page 可选查询

integer · 默认 1

页码，从 1 开始

page_size 可选查询

integer · 默认 20

每页条数，1–100

sort 可选查询

string

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

keyword 可选查询

string

模糊匹配邮箱、昵称或用户 ID

status 可选查询

string

账号状态

可选值activesuspendedpending

role 可选查询

string

角色筛选，可重复传递

可选值owneradminmemberviewer

created_after 可选查询

string

创建时间下界，RFC 3339 格式

fields 可选查询

string

稀疏字段集，逗号分隔以缩减响应体

响应

4 种状态

200 OK

响应示例

{
  "total": 1284,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": "user_7f3a21",
      "email": "ada@acme.com",
      "display_name": "Ada Lovelace",
      "status": "active",
      "roles": [
        "owner"
      ],
      "created_at": "2026-02-11T09:12:00Z"
    },
    {
      "id": "user_5b1e08",
      "email": "alan@acme.com",
      "display_name": "Alan Turing",
      "status": "active",
      "roles": [
        "admin"
      ],
      "created_at": "2026-03-02T14:31:00Z"
    }
  ]
}

代码示例

cURL

curl -i -X GET 'https://api.demo.acme-cloud.dev/v2/users?page=1&page_size=20&sort=-created_at&keyword=ada&status=active&created_after=2026-01-01T00%3A00%3A00Z&fields=id%2Cemail%2Cstatus' \
  -H 'Accept: application/json'