Skip to main content

​
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}")
​
user_id
string
required
Unique identifier for the user. Must be unique within your project.
​
metadata
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}")
​
user_id
string
required
The ID of the user to retrieve.
​
validate
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}")
​
offset
integer
Number of users to skip. Default: 0
​
limit
integer
Maximum number of users to return. Default: 10
​
metadata_filter
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)