Skip to main content
The Client class provides synchronous access to all Avala API resources. It handles authentication, rate limiting, retries, and connection management.

​
Initialization

Create a client instance with your API key: 
from avala import Client

client = Client(api_key="your_api_key")

​
Parameters

​
api_key
str | None
default:"None"
Your Avala API key. If not provided, the SDK will attempt to read from the AVALA_API_KEY environment variable.
​
base_url
str | None
default:"None"
Override the default API base URL. Useful for testing or using a different API environment.
​
timeout
float
default:"30.0"
Request timeout in seconds. Controls how long to wait for a response before raising a timeout error.
​
max_retries
int
default:"2"
Maximum number of retry attempts for failed requests. The SDK automatically retries on network errors and 5xx server errors.

​
Context Manager

The recommended way to use the client is as a context manager, which ensures proper cleanup: 
from avala import Client

with Client(api_key="your_api_key") as client:
    projects = client.projects.list()
    for project in projects:
        print(project.name)
Using the context manager automatically calls client.close() when the block exits, ensuring all network connections are properly closed.

​
Manual Cleanup

If you’re not using a context manager, make sure to call close() when done: 
client = Client(api_key="your_api_key")
try:
    projects = client.projects.list()
finally:
    client.close()

​
Resource Access

The client provides access to all API resources through dedicated properties defined in avala/_client.py:42-57: 
# Datasets
datasets = client.datasets.list()

# Tasks
tasks = client.tasks.list(project_id="proj_123")

# Annotation Issues
issues = client.annotation_issues.list(task_id="task_456")

​
Available Resources

All resources are initialized when the client is created:
  • agents - AI agent management
  • annotation_issues - Annotation quality issues
  • auto_label_jobs - Automated labeling jobs
  • consensus - Consensus annotation tracking
  • datasets - Dataset management
  • exports - Data export operations
  • fleet - Fleet management
  • inference_providers - AI model provider configuration
  • organizations - Organization settings
  • projects - Project management
  • quality_targets - Quality metrics and targets
  • slices - Dataset slicing and filtering
  • storage_configs - Storage configuration
  • tasks - Task management
  • webhooks - Webhook configuration
  • webhook_deliveries - Webhook delivery logs

​
Rate Limit Information

Access rate limit information from the last API response: 
client = Client(api_key="your_api_key")
projects = client.projects.list()

rate_limits = client.rate_limit_info
print(f"Limit: {rate_limits.get('x-ratelimit-limit')}")
print(f"Remaining: {rate_limits.get('x-ratelimit-remaining')}")
print(f"Reset: {rate_limits.get('x-ratelimit-reset')}")
The rate_limit_info property returns a dictionary containing rate limit headers from the most recent API response. It may be empty if no requests have been made yet.

​
Thread Safety

The Client is not thread-safe. Create a separate client instance for each thread, or use proper synchronization mechanisms when sharing a client across threads.

​
Next Steps

AsyncClient

Learn about the async client for concurrent operations

Error Handling

Handle API errors gracefully

Build docs developers (and LLMs) love

Get started for freeTalk to us