Skip to main content
This guide walks you through your first API calls with the Avala SDK. You’ll learn how to initialize the client, list datasets, work with projects, and create exports.

​
Prerequisites

1

Install the SDK

Make sure you have installed the Avala SDK:
pip install avala
2

Get your API key

Obtain your API key from the Avala dashboard. Set it as an environment variable:
export AVALA_API_KEY="avk_your_api_key"

​
Initialize the client

Create a client instance to interact with the Avala API: 
from avala import Client

# Reads AVALA_API_KEY from environment
client = Client()

# Or pass the API key explicitly
client = Client(api_key="avk_your_api_key")

​
List datasets

Retrieve and browse your datasets: 
# List first 10 datasets
page = client.datasets.list(limit=10)

for dataset in page:
    print(f"{dataset.uid}: {dataset.name}")
    print(f"  Type: {dataset.data_type}")
    print(f"  Status: {dataset.status}")

​
Filter datasets

You can filter datasets by data type, status, or visibility: 
# Filter by data type
images = client.datasets.list(data_type="image")

# Filter by status
active = client.datasets.list(status="active")

# Filter by visibility
public = client.datasets.list(visibility="public")

​
Get a specific dataset

Retrieve a single dataset by its unique identifier: 
dataset = client.datasets.get("dataset-uid")

print(f"Dataset: {dataset.name}")
print(f"Owner: {dataset.owner_name}")
print(f"Created: {dataset.created_at}")

​
Work with projects

List all your annotation projects: 
projects = client.projects.list()

for project in projects:
    print(f"{project.uid}: {project.name}")
    print(f"  Status: {project.status}")
Get details about a specific project: 
project = client.projects.get("project-uid")

print(f"Project: {project.name}")
print(f"Dataset: {project.dataset_uid}")
print(f"Task count: {project.task_count}")

​
List tasks

Browse tasks within a project: 
# List all tasks in a project
tasks = client.tasks.list(project="project-uid")

for task in tasks:
    print(f"{task.uid}: {task.status}")

​
Filter tasks by status

Find tasks in a specific state: 
# Find completed tasks
completed = client.tasks.list(
    project="project-uid",
    status="completed"
)

# Find pending tasks
pending = client.tasks.list(
    project="project-uid",
    status="pending"
)

​
Create an export

Export annotated data from your project: 
# Create an export
export = client.exports.create(project="project-uid")

print(f"Export created: {export.uid}")
print(f"Status: {export.status}")

​
Check export status

Poll the export until it’s ready: 
import time

while export.status == "processing":
    time.sleep(5)
    export = client.exports.get(export.uid)
    print(f"Status: {export.status}")

if export.status == "completed":
    print(f"Download URL: {export.download_url}")

​
Pagination

All .list() methods return a CursorPage that supports iteration: 
# Automatic iteration
page = client.datasets.list(limit=20)
for dataset in page:
    print(dataset.name)

# Manual pagination
if page.has_more:
    next_page = client.datasets.list(
        limit=20,
        cursor=page.next_cursor
    )

​
Error handling

Handle API errors gracefully: 
from avala.errors import (
    AvalaError,
    NotFoundError,
    RateLimitError,
    AuthenticationError
)

try:
    dataset = client.datasets.get("nonexistent-uid")
except NotFoundError:
    print("Dataset not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")
except AvalaError as e:
    print(f"API error: {e.message}")

​
Using async client

For async/await support, use AsyncClient: 
from avala import AsyncClient

async def main():
    async with AsyncClient() as client:
        # List datasets
        page = await client.datasets.list(limit=10)
        for dataset in page:
            print(f"{dataset.uid}: {dataset.name}")
        
        # Get a dataset
        dataset = await client.datasets.get("dataset-uid")
        print(f"Dataset: {dataset.name}")
        
        # Create an export
        export = await client.exports.create(project="project-uid")
        print(f"Export: {export.uid}")

# Run the async function
import asyncio
asyncio.run(main())

​
Complete example

Here’s a complete script that ties everything together: 
from avala import Client
from avala.errors import AvalaError

def main():
    # Initialize client
    client = Client()
    
    try:
        # List datasets
        print("Available datasets:")
        datasets = client.datasets.list(limit=5)
        for dataset in datasets:
            print(f"  - {dataset.name} ({dataset.data_type})")
        
        # Get first dataset
        if len(datasets.items) > 0:
            dataset = datasets.items[0]
            print(f"\nWorking with dataset: {dataset.name}")
            
            # List projects
            print("\nProjects:")
            projects = client.projects.list()
            for project in projects:
                print(f"  - {project.name}")
            
            # Get first project
            if len(projects.items) > 0:
                project = projects.items[0]
                
                # List tasks
                print(f"\nTasks in {project.name}:")
                tasks = client.tasks.list(project=project.uid, limit=5)
                for task in tasks:
                    print(f"  - {task.uid}: {task.status}")
                
                # Create export
                print(f"\nCreating export for {project.name}...")
                export = client.exports.create(project=project.uid)
                print(f"Export created: {export.uid}")
                print(f"Status: {export.status}")
    
    except AvalaError as e:
        print(f"Error: {e.message}")
    
    finally:
        client.close()

if __name__ == "__main__":
    main()

​
Next steps

Core Concepts

Learn about the client, pagination, and error handling

Guides

Explore in-depth guides for datasets, projects, and automation

API Reference

Browse the complete API reference

CLI Tool

Use the command-line interface

Build docs developers (and LLMs) love

Get started for freeTalk to us