> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # List organization users > Return the current members of the API key's organization. Requires organization:read. This organization-wide roster is independent of the key's workspace selection. Coval user IDs and timestamps are null for members who have not synchronized to Coval; listing does not create users. Pending invitations and former members are excluded. Headless organizations without a linked Clerk identity return an empty users array and a null next_page_token. They do not accept continuation tokens. Follow next_page_token until it is null to retrieve every member. Tokens are integrity-protected; modified or unsigned tokens return 400. Rotating the Clerk secret invalidates existing tokens; restart pagination from the first page. Members are ordered by Clerk membership creation time ascending. Pagination reflects live membership, rather than a snapshot; changes during traversal can shift page boundaries. Clerk lookup failures return 503 rather than an empty roster. Responses use Cache-Control: no-store, private. Roster reads share a 15-second deadline (reduced when less ingress time remains); exhausted reads return 503. ## OpenAPI ````yaml /api-reference/v1/organization-v1.yaml get /organization/users openapi: 3.0.3 info: title: Coval Organization API version: 1.0.0 description: > List current organization users and read or update organization configuration. Exposes the conversation metrics config for the workspace selected by `X-Coval-Workspace-Id`: the default metrics run on every conversation, plus conditional rules that add metrics based on run metadata. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.dev license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Organization Conversations Config description: >- Workspace-aware configuration for conversation metrics — the default and conditional metrics run on conversations. When no workspace header is supplied, the active default workspace is used when one can be resolved. - name: Organization Users description: Read-only organization membership roster. paths: /organization/users: get: tags: - Organization Users summary: List organization users description: >- Return the current members of the API key's organization. Requires organization:read. This organization-wide roster is independent of the key's workspace selection. Coval user IDs and timestamps are null for members who have not synchronized to Coval; listing does not create users. Pending invitations and former members are excluded. Headless organizations without a linked Clerk identity return an empty users array and a null next_page_token. They do not accept continuation tokens. Follow next_page_token until it is null to retrieve every member. Tokens are integrity-protected; modified or unsigned tokens return 400. Rotating the Clerk secret invalidates existing tokens; restart pagination from the first page. Members are ordered by Clerk membership creation time ascending. Pagination reflects live membership, rather than a snapshot; changes during traversal can shift page boundaries. Clerk lookup failures return 503 rather than an empty roster. Responses use Cache-Control: no-store, private. Roster reads share a 15-second deadline (reduced when less ingress time remains); exhausted reads return 503. operationId: listOrganizationUsers parameters: - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 100 description: Maximum number of members to return in one page. - name: page_token in: query required: false schema: type: string minLength: 1 maxLength: 4096 description: >- Opaque continuation token from a previous response for this organization. responses: '200': description: Current organization members content: application/json: schema: $ref: '#/components/schemas/ListOrganizationUsersResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': description: >- Membership provider or database routing is temporarily unavailable. Retry the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListOrganizationUsersResponse: type: object properties: users: type: array description: Current organization members in this page. items: $ref: '#/components/schemas/OrganizationUser' next_page_token: type: string nullable: true description: Continue with this token; null when no pages remain. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' OrganizationUser: type: object required: - email - display_name properties: id: type: string nullable: true description: Coval user ULID. Null when the member has not synced to Coval. email: type: string description: Member's primary identifier from Clerk; empty when unavailable. display_name: type: string description: Coval display name, falling back to the Clerk name or email. first_name: type: string nullable: true description: First name from Clerk, or null when unset. last_name: type: string nullable: true description: Last name from Clerk, or null when unset. image_url: type: string nullable: true description: Profile image URL from Clerk, or null when unset. created_at: type: string format: date-time nullable: true description: Coval user creation time, or null before synchronization. last_updated_at: type: string format: date-time nullable: true description: Coval user update time, or null before synchronization. Error: type: object required: - code - message properties: code: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - INTERNAL description: Machine-readable error code. example: INVALID_ARGUMENT message: type: string description: Human-readable error message. example: Invalid request body details: type: array maxItems: 100 items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object properties: field: type: string nullable: true description: Field that caused the error, when available. example: default_conversation_metrics description: type: string description: Human-readable detail about the error. example: >- Provide at least one of 'default_conversation_metrics' or 'conditional_conversation_metrics'. responses: BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INVALID_ARGUMENT message: Invalid request body details: - field: conditional_conversation_metrics description: Provide exactly one of 'metric' or 'metrics'. Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: x-api-key description: API key is required in the x-api-key header Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PERMISSION_DENIED message: Insufficient permissions details: - field: permissions description: >- The API key does not include the required organization permission. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Organization not found details: - description: Organization not found. InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: >- An unexpected error occurred while processing the organization request securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.