⌕ ⌘K
GET /v2/users

返回组织内所有用户的分页列表，支持按角色、状态、创建时间筛选。

📅 3天前更新 ✏ 在 GitHub 上编辑

查询参数

Name Type Required Description
page integer required
Page number for pagination. Each page returns a maximum of 100 records.
limit integer
Number of results per page. Default is 20, maximum is 100.
role string
Filter users by role. Supported values: admin, member, viewer.
status string
Filter by account status. Options: active, inactive, pending.
created_after ISO 8601
Return only users created after this timestamp. Example: 2024-01-01T00:00:00Z
sort string
Sort field. Defaults to created_at. Options: name, email, created_at, last_active.

Example Request

# List users, page 1, filter by active members
curl -X GET "https://api.nova.io/v2/users?page=1&limit=20&role=member&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Try It

⚡ API Playground
GET 
{
  "data": [
    {
      "id": "usr_01hx7k2p3m",
      "name": "Lin Wei",
      "email": "lin@example.com",
      "role": "member",
      "status": "active",
      "created_at": "2024-03-15T09:22:00Z",
      "last_active": "2024-11-28T14:05:33Z"
    },
    {
      "id": "usr_01hx7k2q4n",
      "name": "Mariam Okafor",
      "email": "mariam@example.com",
      "role": "admin",
      "status": "active",
      "created_at": "2024-05-02T11:44:18Z",
      "last_active": "2024-11-29T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 248,
    "total_pages": 13,
    "has_more": true
  }
}

Response Fields

Field Type Description
data[].id string
Unique user identifier prefixed with usr_.
data[].name string
Full name of the user.
data[].email string
Email address. Must be verified before the user can access the API.
data[].role string
User's role in the organization. One of admin, member, viewer.
data[].status string
Current account status. Active users can authenticate. Inactive users cannot.
data[].created_at ISO 8601
Timestamp when the user account was created.
data[].last_active ISO 8601
Timestamp of the user's most recent API request or dashboard activity.
pagination object
Pagination metadata object.

Response Codes

200 OK
Request succeeded. Body contains user array and pagination.
400 Bad Request
Invalid query parameters. Check the message field for details.
401 Unauthorized
Missing or invalid API key in the Authorization header.
403 Forbidden
Your API key does not have permission to list users.
429 Too Many Requests
Rate limit exceeded. See the X-RateLimit-Reset header.
500 Internal Error
Something went wrong on our end. Try again in a few minutes.