list_users
Read-onlyIdempotent
Retrieve paginated user data with basic fields (id, name, email, role). Supports cursor, field whitelisting, and structured filters for efficient enumeration.
Instructions
Returns users as paginated skeletons (id, name, email, role, organization_id, active, timestamps). Default limit: 100; pass cursor, fields, filter, or verbose: true. Scope-gated, requires config_plus_audits or full; on config returns scope_blocked. For finding a specific user prefer search (e.g. type:user email:foo@bar.com), full enumeration on a large customer base is rarely the right call. For an agent's SBR skill values, use list_agent_skill_assignments.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max items to return. Default 100. The full corpus is fetched and cached server-side; this only limits what the response carries. | |
| cursor | No | Opaque pagination token from a previous response. Slices the next page from the cached corpus. Stale cursors (older than the cache TTL) auto-reset to offset 0 and set cursor_invalidated: true. | |
| fields | No | Whitelist of field names. Overrides the default projection. Use to opt into extra fields (e.g. ["id","title","active","position","category_id","updated_at"]) without going fully verbose. | |
| filter | No | Structured filter applied to the cached corpus before slicing. Supported keys: active (bool), category_id (number/string), title_contains (string, case-insensitive), updated_since (ISO timestamp). Unsupported keys are ignored with a note in the response. | |
| refresh | No | Bypass cache and re-fetch from Zendesk | |
| verbose | No | Return full user objects instead of the thin projection | |
| instance | No | Override the sticky instance for this call |