---
title: "Retrieve list of users with filtering, sorting, and pagination."
method: GET
path: "/api/v1/user"
---

# Retrieve list of users with filtering, sorting, and pagination.

`GET /api/v1/user`

**Authentication**: JWT token required
**Access**: Restricted to ADMIN and SUPERADMIN users only

**Query Parameters**:
- `include`: Comma-separated list of additional fields to include
- `exclude`: Comma-separated list of fields to exclude from response
- `filter`: Filter users by email, name, role, or other attributes
- `sort`: Sort field (prefix with '-' for descending, e.g., '-created_at')
- `page`: Page number for pagination (triggers pagination when provided)
- `per_page`: Items per page (1-100, default: 20)

**Response Schema (without pagination)**:
```json
{
  "data": [
    {
      "id": "123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "USER",
      "country": "US",
      "institution": "Example Organization",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "last_login_at": "2025-01-15T09:30:00Z",
      "last_activity_at": "2025-01-15T11:30:00Z",
      "email_verified": true,
      "email_verified_at": "2025-01-15T10:30:00Z"
    }
  ]
}
```

**Response Schema (with pagination)**:
```json
{
  "data": [...],
  "page": 1,
  "per_page": 20,
  "total": 150
}
```

**Filtering Examples**:
- `?filter=role=ADMIN` - Find users with ADMIN role
- `?filter=country=US` - Find users from United States
- `?filter=email_verified=true` - Find users who verified their email
- `?filter=last_activity_at>2025-01-01` - Find users active after date

**Sorting Examples**:
- `?sort=name` - Sort by name ascending
- `?sort=-created_at` - Sort by creation date descending
- `?sort=last_activity_at desc` - Sort by last activity descending
- `?sort=-email_verified` - Sort unverified users first

**Field Control Examples**:
- `?include=password_last_changed` - Include additional fields
- `?exclude=institution,country` - Exclude specified fields

**Error Responses**:
- `401 Unauthorized`: JWT token required
- `403 Forbidden`: Insufficient privileges (ADMIN+ required)
- `500 Internal Server Error`: Failed to retrieve users

## Response `200`

Success

- object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/trends/apis/trends-earth-api.md) · [All operations](https://skmtc.dev/trends/apis/trends-earth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trends/trends-earth-api/revisions/6bdbc0b84666/schema)