> ## Documentation Index > Fetch the complete documentation index at: https://docs.usertour.io/llms.txt > Use this file to discover all available pages before exploring further. # List users ## OpenAPI ````yaml /api-reference-v2/openapi.json get /v2/projects/{projectId}/environments/{environmentId}/users openapi: 3.0.0 info: title: Usertour API v2 description: >- Project-scoped v2 API. Authenticate with a personal API token — an opaque `utp_...` string (NOT a JWT: do not try to decode it), created in the Usertour app under Settings → API, sent as `Authorization: Bearer utp_...`. version: '2.0' contact: {} servers: - url: https://api.usertour.io security: [] tags: [] paths: /v2/projects/{projectId}/environments/{environmentId}/users: get: tags: - Users summary: List users operationId: ApiUsersController_list parameters: - name: limit required: false in: query description: Max items per page (1-100, default 20). schema: minimum: 1 maximum: 100 default: 20 type: integer - name: cursor required: false in: query description: >- Opaque page cursor — the `cursor` query value found inside a prior response's `next`/`previous` URL. Normally you never build this yourself: just GET those URLs as-is. schema: type: string - name: orderBy required: false in: query description: Order by createdAt / -createdAt. schema: anyOf: - type: string enum: - createdAt - '-createdAt' - type: array items: type: string enum: - createdAt - '-createdAt' - name: expand required: false in: query description: 'Inline: companies, memberships, memberships.company.' schema: anyOf: - type: string enum: - companies - memberships - memberships.company - type: array items: type: string enum: - companies - memberships - memberships.company - name: email required: false in: query description: Filter to a user with this email. schema: format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ type: string - name: companyId required: false in: query description: Filter to users in this company. schema: type: string - name: segmentId required: false in: query description: Filter to users in this segment. schema: type: string - name: createdAfter required: false in: query description: >- Only items created at or after this time — ISO date or datetime WITH timezone. A date-only value starts at that day's first instant (UTC). schema: type: string - name: createdBefore required: false in: query description: >- Only items created at or before this time — ISO date or datetime WITH timezone. A date-only value includes the ENTIRE day (up to its last instant, UTC). schema: type: string - name: environmentId required: true in: path description: Environment ID schema: type: string - name: projectId required: true in: path description: Project ID schema: type: string responses: '200': description: List of users content: application/json: schema: $ref: '#/components/schemas/ListUsersResponseDto' '400': description: >- Invalid request — E1017 validation (may carry `issues`; an invalid orderBy/limit is also E1017), E1015 invalid scope, E0003 invalid against current domain state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '401': description: Missing or expired API key — E1010, E1020. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '403': description: >- Refused — E1000 invalid key, E1011 project not in token scope, E1012 insufficient scope, E1029 environment not in token scope, E1032 environment creation needs a token without env-targeted capabilities (its allowlist cannot cover a not-yet-existing environment). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '429': description: >- Rate limit exceeded — E1013. The limit follows the project's plan (100/500/1000/3000 requests per minute); unknown credentials share a per-IP bucket. Every response also carries X-RateLimit-Limit / -Remaining / -Reset for pacing; a 429 adds the standard Retry-After header (seconds to back off). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - bearer: [] components: schemas: ListUsersResponseDto: type: object properties: results: type: array items: type: object properties: id: type: string description: >- External user id — the id your app supplied at identify/upsert. object: type: string enum: - user attributes: type: object additionalProperties: {} createdAt: type: string format: date-time companies: type: array items: type: object properties: id: type: string object: type: string enum: - company attributes: type: object additionalProperties: {} createdAt: type: string format: date-time required: - id - object - attributes - createdAt description: >- null = not expanded (pass expand: ["companies"]); [] = expanded, none. nullable: true memberships: type: array items: type: object properties: id: type: string description: >- Internal membership record id (not addressable anywhere) — join on userId/companyId instead. object: type: string enum: - companyMembership attributes: type: object additionalProperties: {} createdAt: type: string format: date-time companyId: type: string description: External company id — the id companies are addressed by. userId: type: string description: External user id — the id users are addressed by. company: type: object properties: id: type: string object: type: string enum: - company attributes: type: object additionalProperties: {} createdAt: type: string format: date-time required: - id - object - attributes - createdAt required: - id - object - attributes - createdAt - companyId - userId description: >- null = not expanded (pass expand: ["memberships"]); [] = expanded, none. nullable: true required: - id - object - attributes - createdAt - companies - memberships next: type: string description: >- Full URL of the next page — request it as-is (it already carries `cursor=` and your query parameters). null = no further pages. nullable: true previous: type: string description: >- Full URL of the previous page — request it as-is. null = already at the first page. nullable: true required: - results - next - previous ErrorResponseDto: type: object properties: error: type: object properties: code: type: string description: >- Stable machine-readable code (e.g. E1017). Match on this, never on `message`. message: type: string description: Human-readable summary. Wording may change between releases. issues: description: >- Validation errors (E1017) may carry one entry per problem so every field can be fixed in a single round-trip. Absent on other errors. type: array items: type: object properties: rule: type: string description: >- Which validation layer rejected it: schema | reactive_condition | action_not_allowed | step_shape | reference_target | auto_start | media_url. New values may be added; treat an unknown value as a generic validation failure. message: type: string path: description: >- Path into the request body (e.g. `steps[0].triggers[0].when[1]`). type: string required: - rule - message doc_url: type: string description: Base URL of the API documentation. required: - error securitySchemes: bearer: scheme: bearer bearerFormat: utp_... personal API token (opaque) type: http ````