*MCP › 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.

TOOL `filmo_users_list` · `users:read` · 120/min · Server annotation: Read-only · Server annotation: Idempotent

## Arguments

| 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. |
| `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` |
| `dateFilters` | object | No | Date filters by field. A bare day (YYYY-MM-DD) is read in the business timezone; an ISO 8601 instant with offset is applied as is by gte, lte, gt and lt, while on widens it to the whole business day that contains it. Fields: created, updated. |
| `dateFilters.created` | object | No |  |
| `dateFilters.created.gte` | string | No | From this day or instant, inclusive. |
| `dateFilters.created.lte` | string | No | Up to this day or instant, inclusive. |
| `dateFilters.created.gt` | string | No | Strictly after; a bare day means after the end of that day. |
| `dateFilters.created.lt` | string | No | Strictly before; a bare day means before the start of that day. |
| `dateFilters.created.on` | string | No | Exactly that day; an instant means the whole business day that contains it. |
| `dateFilters.updated` | object | No |  |
| `dateFilters.updated.gte` | string | No | From this day or instant, inclusive. |
| `dateFilters.updated.lte` | string | No | Up to this day or instant, inclusive. |
| `dateFilters.updated.gt` | string | No | Strictly after; a bare day means after the end of that day. |
| `dateFilters.updated.lt` | string | No | Strictly before; a bare day means before the start of that day. |
| `dateFilters.updated.on` | string | No | Exactly that day; an instant means the whole business day that contains it. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the user. It is the value other resources carry in `createdBy`, `mentionedUserIds` and the like. |
| `name` | string | Display name. |
| `email` | string | Email the person signs in with. |
| `role` | object | Role in this account. |
| `role.id` | string | Identifier of the role: owner, super-admin, admin, a predefined role or `custom`. |
| `role.name` | string | Name of the role, in the language of the account. |
| `isAdmin` | boolean | true when the role administers the account. |
| `status` | string | Access status: active, pending (invited, not yet accepted) or inactive. `active`, `pending`, `inactive` |
| `staffMemberId` | string | Identifier of the staff member this user is linked to (see `/api/v1/staff`); null if none. |
| `createdAt` | string<date-time> | Date the user account was created in ISO 8601 UTC; null for an invitation not yet accepted. |
| `updatedAt` | string<date-time> | Last modification date of the user account in ISO 8601 UTC; null for an invitation not yet accepted. |

*Call · filmo_users_list*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_users_list",
    "arguments": {
      "limit": 20
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": [
      {
        "id": "id_8f2a1c",
        "name": "Example",
        "email": "ana@example.com",
        "role": {
          "id": "id_8f2a1c",
          "name": "Example"
        },
        "isAdmin": true,
        "status": "active",
        "staffMemberId": "staf_8f2a1c",
        "createdAt": "2026-09-01T08:00:00Z",
        "updatedAt": "2026-09-01T08:00:00Z"
      }
    ],
    "pagination": {
      "nextCursor": "eyJvIjo1MH0",
      "hasMore": true,
      "total": 1
    },
    "meta": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`GET /api/v1/users`](https://docs.filmo.io/rest-api/endpoint-reference/users/list-users).

---

Canonical URL: https://docs.filmo.io/mcp/tools/users/filmo-users-list  
Last updated: 2026-10-25