> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Organization Users

> Retrieve all users in your organization with their details, roles, activity status, and metadata

<Warning>
  **DEPRECATED:** This endpoint has been replaced by the new RESTful API structure.

  Please migrate to:

  * [GET /admin/users](/api-reference/admin-api/list-organization-users) - For active users
  * [GET /admin/invitations](/api-reference/admin-api/list-organization-invitations) - For pending invitations

  This endpoint will be removed in a future version.
</Warning>

<Note>
  This endpoint requires organization admin privileges. Only users with the `org:admin` role can access organization user data.
</Note>

Returns a list of all users and pending invitations for the organization, including their profile information, roles, activity status, and custom metadata. Perfect for user management automation and bulk operations.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Must be from a user with `org:admin` role.
</ParamField>

## Query Parameters

<ParamField query="activityStatus" type="string">
  Filter users by activity status. Options: `active`, `pending`, `inactive`
</ParamField>

<ParamField query="role" type="string">
  Filter users by organization role. Options: `org:admin`, `org:member`
</ParamField>

## Response

Returns an array of user objects with comprehensive details:

<ResponseField name="id" type="string" nullable>
  Unique Clerk user identifier. `null` for pending invitations that haven't been accepted.
</ResponseField>

<ResponseField name="email" type="string">
  User's email address
</ResponseField>

<ResponseField name="firstName" type="string" nullable>
  User's first name
</ResponseField>

<ResponseField name="lastName" type="string" nullable>
  User's last name
</ResponseField>

<ResponseField name="username" type="string" nullable>
  User's username (if set)
</ResponseField>

<ResponseField name="profileImageUrl" type="string" nullable>
  URL to user's profile image/avatar
</ResponseField>

<ResponseField name="lastSignInAt" type="string" nullable>
  ISO 8601 timestamp of user's last sign-in
</ResponseField>

<ResponseField name="publicMetadata" type="object">
  Organization-scoped user metadata (department, role, vnum, etc.). Each organization maintains separate metadata for shared users.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when user account was created
</ResponseField>

<ResponseField name="role" type="string">
  User's role in the organization (e.g., "org:admin", "org:member")
</ResponseField>

<ResponseField name="activityStatus" type="string">
  User's activity status: `active` (current member), `pending` (invitation sent but not accepted), `inactive` (invitation revoked)
</ResponseField>

<ResponseField name="invitationStatus" type="string" nullable>
  Clerk invitation status if applicable: `pending`, `accepted`, `revoked`, or `null` for users without invitation history
</ResponseField>

<ResponseField name="invitationCreatedAt" type="string" nullable>
  ISO 8601 timestamp when invitation was created, or `null` for users without invitation history
</ResponseField>

### Examples

<CodeGroup>
  ```curl theme={null}
  curl -X GET "https://asteragents.com/api/admin/getUsersInOrg?activityStatus=active&role=org:admin" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```javascript theme={null}
  const response = await fetch('/api/admin/getUsersInOrg?activityStatus=active', {
    headers: {
      'Authorization': 'Bearer ' + token
    }
  });

  const activeUsers = await response.json();
  console.log(`Found ${activeUsers.length} active users`);
  ```

  ```python theme={null}
  import requests

  response = requests.get(
      'https://asteragents.com/api/admin/getUsersInOrg',
      headers={'Authorization': f'Bearer {token}'}
  )

  users = response.json()
  print(f"Found {len(users)} users in organization")
  ```

  ```json Response theme={null}
  [
    {
      "id": "user_2ABC123DEF",
      "email": "john.doe@company.com",
      "firstName": "John",
      "lastName": "Doe",
      "username": "johndoe",
      "profileImageUrl": "https://img.clerk.com/profile.jpg",
      "lastSignInAt": "2024-01-15T10:30:00.000Z",
      "publicMetadata": {
        "department": "engineering",
        "role": "manager",
        "vnum": "123",
        "team": "backend"
      },
      "createdAt": "2023-12-01T08:00:00.000Z",
      "role": "org:admin",
      "activityStatus": "active",
      "invitationStatus": null,
      "invitationCreatedAt": null
    },
    {
      "id": "user_2XYZ789GHI",
      "email": "sarah.smith@company.com",
      "firstName": "Sarah",
      "lastName": "Smith",
      "username": null,
      "profileImageUrl": null,
      "lastSignInAt": "2024-01-14T16:45:00.000Z",
      "publicMetadata": {
        "department": "marketing",
        "role": "member",
        "vnum": "456"
      },
      "createdAt": "2024-01-10T12:30:00.000Z",
      "role": "org:member",
      "activityStatus": "active",
      "invitationStatus": null,
      "invitationCreatedAt": null
    },
    {
      "id": null,
      "email": "pending.user@company.com",
      "firstName": null,
      "lastName": null,
      "username": null,
      "profileImageUrl": null,
      "lastSignInAt": null,
      "publicMetadata": {},
      "createdAt": "2024-01-20T09:15:00.000Z",
      "role": "org:member",
      "activityStatus": "pending",
      "invitationStatus": "pending",
      "invitationCreatedAt": "2024-01-20T09:15:00.000Z"
    }
  ]
  ```
</CodeGroup>

### Error Codes

<ResponseField name="400" type="object">
  Bad Request - User is not part of any organization
</ResponseField>

<ResponseField name="401" type="object">
  Unauthorized - Invalid or missing authentication
</ResponseField>

<ResponseField name="403" type="object">
  Forbidden - User is not an admin in the organization
</ResponseField>

<ResponseField name="405" type="object">
  Method Not Allowed - Only GET requests are accepted
</ResponseField>

<ResponseField name="500" type="object">
  Internal Server Error - Unexpected error occurred
</ResponseField>

## Use Cases

### Bulk User Operations

Filter and process users based on metadata:

```javascript theme={null}
// Find all users in engineering department
const engineeringUsers = users.filter(user => 
  user.publicMetadata?.department === 'engineering'
);

// Find users by vnum
const specificUsers = users.filter(user => 
  user.publicMetadata?.vnum === '123'
);
```

### User Management Dashboard

Build custom admin interfaces with complete user data:

```python theme={null}
# Create user summary report
for user in users:
    print(f"{user['email']} - {user['role']} - Last active: {user['lastSignInAt']}")
```

### Invitation Status Check

Use this endpoint to verify which users have accepted invitations:

```javascript theme={null}
// Users with recent sign-ins have likely accepted invitations
const activeUsers = users.filter(user => user.lastSignInAt);
const pendingUsers = users.filter(user => !user.lastSignInAt);
```

## Features

**Complete User Data**: Access all user profile information, roles, and custom metadata in a single request.

* **Organization-Scoped Metadata**: Each organization maintains separate metadata for users - perfect for multi-org scenarios
* **Metadata Filtering**: Use publicMetadata to filter users by department, role, vnum, or any custom fields within your organization
* **Role Management**: See each user's organization role (admin vs member)
* **Activity Tracking**: Check last sign-in times to identify active vs inactive users
* **Bulk Operations**: Process multiple users programmatically for invitations, role changes, etc.

## Notes

* Results are ordered by email address alphabetically
* Only returns users who are active members of the organization
* **Metadata is organization-scoped**: Users in multiple organizations have separate metadata per org
* Metadata structure depends on what was set during user invitation or updates via [Update User Metadata](/api-reference/endpoint/update-user-metadata)
* `lastSignInAt` will be null for users who haven't signed in yet (pending invitations)
* Use this data to identify users for bulk operations like role updates or removal