*REST API › Endpoint reference › Account & access › Users*

# List users

> Returns the people with access to the account — the ones who sign in to Filmo, not the staff — with their role, whether they administer the account, the status of their access (active, pending invitation or inactive) and the staff member they are linked to.

It emits no credentials, sessions, permissions or preferences. Administrators only. Sorted by name.

`GET /api/v1/users` — scope `users:read`

Scope: `users:read` · 120/min · MCP: `filmo_users_list`

## Authorizations

Bearer API key with the scope below. `users:read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` |
| `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. |
| `createdOn` | string | No | The creation date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdAfter` | string | No | The creation date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdBefore` | string | No | The creation date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdFrom` | string | No | The creation date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdTo` | string | No | The creation date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedOn` | string | No | The last update date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedAfter` | string | No | The last update date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedBefore` | string | No | The last update date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedFrom` | string | No | The last update date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedTo` | string | No | The last update date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: name, email, status, createdAt, updatedAt. Defaults to "name". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. |
| `status` | string | No | Filter by access status: active, pending (invited, not yet accepted) or inactive. `active`, `pending`, `inactive` |
| `statuses` | string[] | No | Filter by status, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. `active`, `pending`, `inactive` |
| `isAdmin` | boolean | No | Filter by whether the user is an administrator of the account (true) or not (false). |
| `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` |

## Request examples

*List users*

**cURL**

```bash
curl https://app.filmo.io/api/v1/users \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/users', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get("https://app.filmo.io/api/v1/users",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Response

Response schema: `UserDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.id` | string | Unique identifier of the user. It is the value other resources carry in `createdBy`, `mentionedUserIds` and the like. |
| `data.name` | string | Display name. |
| `data.email` | string | Email the person signs in with. |
| `data.role` | object | Role in this account. |
| `data.role.id` | string | Identifier of the role: owner, super-admin, admin, a predefined role or `custom`. |
| `data.role.name` | string | Name of the role, in the language of the account. |
| `data.isAdmin` | boolean | true when the role administers the account. |
| `data.status` | string | Access status: active, pending (invited, not yet accepted) or inactive. `active`, `pending`, `inactive` |
| `data.staffMemberId` | string | Identifier of the staff member this user is linked to (see `/api/v1/staff`); null if none. |
| `data.createdAt` | string<date-time> | Date the user account was created in ISO 8601 UTC; null for an invitation not yet accepted. |
| `data.updatedAt` | string<date-time> | Last modification date of the user account in ISO 8601 UTC; null for an invitation not yet accepted. |
| `pagination` | object | Opaque-cursor pagination metadata. |
| `pagination.nextCursor` | string | Opaque cursor of the next page; null when there are no more results. Pass it as `cursor` in the next request. |
| `pagination.hasMore` | boolean | Whether more results exist beyond this page. |
| `pagination.total` | integer | Number of results matching the filters across all pages. Present only when the request sets `includeTotal=true`. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "id": "user_9f3a2b",
      "name": "Example user",
      "email": "ana.garcia@example.com",
      "role": {
        "id": "role_9f3a2b",
        "name": "Example role"
      },
      "isAdmin": true,
      "status": "active",
      "staffMemberId": "staff_member_9f3a2b",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/users/list-users  
Last updated: 2026-10-25