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

# RecallrAI Client

> Main client class for interacting with RecallrAI

## Overview

The `RecallrAI` client is the entry point for all SDK operations. It manages authentication and provides methods for user management.

## Initialization

```python theme={null}
from recallrai import RecallrAI

client = RecallrAI(
    api_key="rai_yourapikey",
    project_id="project-uuid",
    base_url="https://api.recallrai.com",  # optional
    timeout=60,  # optional
)
```

## Methods

### create\_user()

Create a new user in your project.

```python theme={null}
from recallrai.exceptions import UserAlreadyExistsError

try:
    user = client.create_user(
        user_id="user123",
        metadata={"name": "John Doe", "role": "admin"}
    )
    print(f"Created user: {user.user_id}")
except UserAlreadyExistsError as e:
    print(f"Error: {e}")
```

<ParamField path="user_id" type="string" required>
  Unique identifier for the user. Must be unique within your project.
</ParamField>

<ParamField path="metadata" type="dict">
  Optional metadata to associate with the user. Can contain any JSON-serializable data.
</ParamField>

**Returns:** `User` object

**Raises:** `UserAlreadyExistsError` if user\_id already exists

***

### get\_user()

Retrieve an existing user by ID.

```python theme={null}
from recallrai.exceptions import UserNotFoundError

try:
    user = client.get_user("user123")
    print(f"User metadata: {user.metadata}")
except UserNotFoundError as e:
    print(f"Error: {e}")
```

<ParamField path="user_id" type="string" required>
  The ID of the user to retrieve.
</ParamField>

<ParamField path="validate" type="boolean" default="True">
  Whether to validate user existence via API before creating the instance. Set `False` only when `user_id` is already trusted.
</ParamField>

**Returns:** `User` object

**Raises:** `UserNotFoundError` if user doesn't exist

<Tip>
  Set `validate=False` to skip the SDK lookup request (`GET /api/v1/users/{user_id}`) when the user ID is already trusted by your system.
</Tip>

<Note>
  When `validate=False`, fields that require an API lookup (for example `created_at`, `last_active_at`, and `metadata`) are set to `UNAVAILABLE` until you call `refresh()`.
  Import `UNAVAILABLE` from `recallrai.models` when checking these values.
</Note>

***

### list\_users()

List all users in your project with optional filtering and pagination.

```python theme={null}
user_list = client.list_users(
    offset=0,
    limit=10,
    metadata_filter={"role": "admin"}
)

print(f"Total users: {user_list.total}")
print(f"Has more: {user_list.has_more}")

for user in user_list.users:
    print(f"User ID: {user.user_id}")
    print(f"Metadata: {user.metadata}")
```

<ParamField path="offset" type="integer">
  Number of users to skip. Default: `0`
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of users to return. Default: `10`
</ParamField>

<ParamField path="metadata_filter" type="dict">
  Filter users by metadata fields. Only users matching all specified fields are returned.
</ParamField>

**Returns:** `UserList` object with:

* `users`: List of `User` objects
* `total`: Total number of users matching the filter
* `has_more`: Boolean indicating if more results are available

## Async Client

For async applications, use `AsyncRecallrAI`:

```python theme={null}
from recallrai import AsyncRecallrAI

client = AsyncRecallrAI(
    api_key="rai_yourapikey",
    project_id="project-uuid"
)

# All methods are the same, just use await
user = await client.create_user("user123")
user = await client.get_user("user123")
user_list = await client.list_users(limit=20)
```