RecallrAI Client

Overview

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

Initialization

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.

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}")

string

required

Unique identifier for the user. Must be unique within your project.

dict

Optional metadata to associate with the user. Can contain any JSON-serializable data.

Returns: User object Raises: UserAlreadyExistsError if user_id already exists

get_user()

Retrieve an existing user by ID.

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}")

string

required

The ID of the user to retrieve.

boolean

default:"True"

Whether to validate user existence via API before creating the instance. Set False only when user_id is already trusted.

Returns: User object Raises: UserNotFoundError if user doesn’t exist

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.

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.

list_users()

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

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}")

integer

Number of users to skip. Default: 0

integer

Maximum number of users to return. Default: 10

dict

Filter users by metadata fields. Only users matching all specified fields are returned.

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:

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)

Python

Node.js

Overview

Initialization

Methods

create_user()

get_user()

list_users()

Async Client

​Overview

​Initialization

​Methods

​create_user()

​get_user()

​list_users()

​Async Client

Overview

Initialization

Methods

create_user()

get_user()

list_users()

Async Client