> ## Documentation Index > Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt > Use this file to discover all available pages before exploring further. # List all users in the organization > Retrieve all users in the organization with their seat assignment status and role information. Rate limited to 10 requests per 60 seconds per organization. ## OpenAPI ````yaml /openapi.json get /v1/users openapi: 3.0.3 info: title: CodeRabbit API spec version: 1.0.0 servers: - url: https://api.coderabbit.ai security: - ApiKeyAuth: [] paths: /v1/users: get: tags: - User Management summary: List all users in the organization description: >- Retrieve all users in the organization with their seat assignment status and role information. Rate limited to 10 requests per 60 seconds per organization. operationId: list-users parameters: - in: header name: x-coderabbitai-api-key required: true schema: type: string description: API key for authentication - in: query name: org_id required: false schema: type: string description: >- Workspace-scoped API tokens only. When provided, lists users for that single git-provider organization within the token's workspace; when omitted, returns a workspace-wide, person-centric view across all organizations in the workspace. Ignored for organization and self-hosted keys. - in: query name: seat_filter required: false schema: type: string enum: - all - assigned - unassigned default: all description: >- Filter users by seat assignment status. Options are "all" (default), "assigned" (users with seats), or "unassigned" (users without seats). - in: query name: role_filter required: false schema: type: string enum: - all - member - admin default: all description: >- Filter users by system role. Options are "all" (default), "member" (cr_member role only), or "admin" (cr_admin role only). - in: query name: role_id_filter required: false schema: type: string description: >- Filter users by an exact role ID. Use cr_admin, cr_member, or a custom role UUID. - in: query name: membership required: false schema: type: string enum: - org - non_org - all default: org description: >- Filter users by workspace-org membership. "org" (default) returns only members of a workspace org, hiding external contributors (e.g. authors of pull requests on public repositories); "non_org" returns only those external contributors; "all" returns everyone. - in: query name: linked required: false schema: type: boolean description: >- Workspace-wide SSO user rosters only. When true, returns users with a non-null email and at least one active linked account. When false, returns users whose email is null or who have no active linked accounts. Supplying this parameter for an organization-scoped or non-SSO read returns 400. - in: query name: email required: false schema: type: string format: email description: >- Workspace-wide SSO rosters only (workspace token, omit org_id). Exact case-insensitive member email match, with surrounding whitespace trimmed. Mutually exclusive with username. Applied before pagination and combined with seat_filter, linked, and membership; seat totals remain workspace-wide. Workspace reads do not apply role_filter or role_id_filter. - in: query name: username required: false schema: type: string minLength: 1 description: >- Workspace-wide SSO rosters only (workspace token, omit org_id). Exact case-insensitive linked username match, with surrounding whitespace trimmed, across all cloud providers and self-hosted instances. Only non-removed identities in active workspace subscriptions match. Returns each matching person once with all their linked accounts; multiple people may match. Mutually exclusive with email. Applied before pagination. Repeat the lookup parameters on subsequent pages. - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 100 default: 100 description: Maximum number of users to return per page. - in: query name: cursor required: false schema: type: string description: Pagination cursor from previous response's next_cursor field. responses: '200': description: Successfully retrieved list of users headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per time window (10) X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current window X-RateLimit-Reset: description: Unix timestamp when the rate limit resets schema: type: integer content: application/json: schema: type: object required: - seats_purchased - seats_assigned - seat_assignment_mode - users - next_cursor properties: seats_purchased: type: integer description: Total number of seats purchased in the subscription example: 50 seats_assigned: type: integer description: Number of seats currently assigned to users example: 30 seat_assignment_mode: type: string enum: - automatic - manual description: The seat assignment mode for the organization example: manual users: type: array description: >- Item shape depends on the token scope. Organization, self-hosted, and org-selected workspace tokens (org_id present) return the org-scoped object. Workspace-scoped tokens with no org_id return the workspace-wide, person-centric object. items: oneOf: - type: object title: >- Org-scoped (organization, self-hosted, org-selected workspace tokens) required: - user_id - username - seat_assigned - role - role_name - role_type properties: user_id: type: string description: >- The provider user ID (Git provider's user identifier, e.g., GitHub user ID) example: '121358802' username: type: string nullable: true description: >- The provider username associated with user_id, or null when the profile has not supplied one yet. example: janedoe seat_assigned: type: boolean description: Whether the user has an assigned seat example: true role: type: string description: >- The user's role ID in the organization. Custom roles return their UUID. example: 6f1bb6c1-4766-4f09-9d0d-b998c33d2398 role_name: type: string description: Human-readable role name. example: Security Reviewer role_type: type: string enum: - system - custom description: >- Whether the role is a built-in system role or a custom role. example: custom - type: object title: >- Workspace person-centric (workspace tokens, no org_id) required: - cr_user_id - seat_assigned - role - email - workspace_role - accounts properties: cr_user_id: type: string description: >- The CodeRabbit user id (cr_users.id) for the person within the workspace. Pass it back as the seat member cr_user_id on POST /users/seats. Distinct from the provider accounts[].user_id. example: f1bb6c14-7664-4f09-9d0d-b998c33d2398 seat_assigned: type: boolean description: >- Whether the person holds a workspace seat (cr_users.is_seat_assigned). example: true role: type: string nullable: true description: >- Always null in the workspace-wide view; per-membership roles are on each accounts[] entry. example: null email: type: string format: email nullable: true description: The person's email address, if known. example: jane@acme.com workspace_role: type: string nullable: true description: >- The person's workspace-level role id (e.g., cr_admin, cr_member), or null. example: cr_admin accounts: type: array description: >- One entry per subscription_user (seat-ledger) identity linked to this person. Sourced from subscription_user, not cr_user_external_accounts, so a member with a linked seat row but no external account still lists it here. items: type: object required: - provider - self_hosted - user_id - username properties: provider: type: string description: >- Git provider for this account (e.g., github, gitlab). example: github self_hosted: type: boolean description: >- Whether this account belongs to a self-hosted instance. example: false instance_url: type: string nullable: true description: Self-hosted instance URL, if applicable. example: null organization_id: type: string nullable: true description: >- Always null on this path (a subscription_user carries no org-membership context). example: null user_id: type: string description: The provider user ID for this account. example: '121358802' username: type: string nullable: true description: The provider username for this account. example: janedoe role: type: string nullable: true description: >- Always null on this path (a subscription_user carries no org role). example: null next_cursor: type: string nullable: true description: >- Cursor for the next page of results, or null if no more results example: MTIxMzU4ODAy '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - INVALID_REQUEST example: INVALID_REQUEST message: type: string example: >- Invalid seat_filter. Must be one of: "all", "assigned", "unassigned" OR Invalid role_filter. Must be one of: "all", "member", "admin" '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHORIZED example: UNAUTHORIZED message: type: string example: Invalid or inactive API key '403': description: Forbidden - Missing required permission or Enterprise plan content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - FORBIDDEN - ENTERPRISE_PLAN_REQUIRED example: FORBIDDEN message: type: string example: User does not have the required permissions '410': description: >- Legacy API key - deprecated and no longer supported for user management content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - LEGACY_API_KEY example: LEGACY_API_KEY message: type: string example: >- You are using a legacy API key. We are deprecating use of legacy keys. Regenerate a new API key and retry the request. '429': description: Rate limit exceeded (10 requests per 60 seconds per organization) headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per time window schema: type: integer X-RateLimit-Remaining: description: Always 0 when rate limited schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the rate limit resets schema: type: integer content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - RATE_LIMIT_EXCEEDED example: RATE_LIMIT_EXCEEDED message: type: string example: Rate limit exceeded. Max 10 requests per 60 seconds '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - INTERNAL_ERROR example: INTERNAL_ERROR message: type: string example: Internal server error while listing users security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-coderabbitai-api-key description: >- API key for authentication. You can create an API key from the CodeRabbit dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.