Skip to main content

​
Overview

This guide will walk you through making your first API calls with the Avala SDK. You’ll learn how to initialize the client, list datasets, create exports, and handle responses.
Make sure you’ve installed the SDK and have an API key ready. If you don’t have an API key yet, see Authentication.

​
Initialize the client

First, set your API key as an environment variable: 
export AVALA_API_KEY="avk_your_api_key"
Then import and initialize the Avala client: 
import Avala from "@avala-ai/sdk";

const avala = new Avala();
The client automatically reads your API key from the AVALA_API_KEY environment variable. You can also pass it explicitly: new Avala({ apiKey: "avk_..." })

​
List datasets

Let’s start by listing your available datasets: 
const page = await avala.datasets.list({ limit: 10 });

page.items.forEach(dataset => {
  console.log(`${dataset.uid} - ${dataset.name}`);
  console.log(`  Items: ${dataset.itemCount}`);
  console.log(`  Type: ${dataset.dataType}`);
});

let page = await avala.datasets.list({ limit: 20 });

for (const dataset of page.items) {
  console.log(dataset.name);
}

// Load next page if available
if (page.hasMore) {
  const nextPage = await avala.datasets.list({ 
    cursor: page.nextCursor 
  });
}

​
Get a specific dataset

Retrieve detailed information about a single dataset: 
const dataset = await avala.datasets.get("dataset-uid");

console.log(`Dataset: ${dataset.name}`);
console.log(`Slug: ${dataset.slug}`);
console.log(`Items: ${dataset.itemCount}`);
console.log(`Created: ${dataset.createdAt}`);

​
Create an export

Exports allow you to download annotated data from a project: 
const exp = await avala.exports.create({ 
  project: "project-uid" 
});

console.log(`Export UID: ${exp.uid}`);
console.log(`Status: ${exp.status}`);
1

Create the export

Call avala.exports.create() with a project UID to start a new export.
2

Poll for completion

The export processes asynchronously. Poll avala.exports.get(exp.uid) until status is "completed".
3

Download the data

Once complete, use the downloadUrl field to retrieve your annotated data.

​
List tasks with filters

Query tasks with filters to find specific annotation work: 
const tasks = await avala.tasks.list({
  project: "project-uid",
  status: "completed",
  limit: 25
});

tasks.items.forEach(task => {
  console.log(`${task.name} (${task.status})`);
});

​
Complete example

Here’s a complete working example that ties everything together: 
import Avala from "@avala-ai/sdk";

const avala = new Avala();

async function main() {
  // List datasets
  console.log("📊 Fetching datasets...");
  const datasets = await avala.datasets.list({ limit: 5 });
  
  console.log(`Found ${datasets.items.length} datasets:\n`);
  datasets.items.forEach(d => {
    console.log(`  • ${d.name} (${d.itemCount} items)`);
  });

  // Get a specific dataset
  if (datasets.items.length > 0) {
    const firstDataset = datasets.items[0];
    console.log(`\n🔍 Fetching details for "${firstDataset.name}"...`);
    
    const dataset = await avala.datasets.get(firstDataset.uid);
    console.log(`  Slug: ${dataset.slug}`);
    console.log(`  Type: ${dataset.dataType}`);
  }

  // List projects
  console.log("\n📁 Fetching projects...");
  const projects = await avala.projects.list({ limit: 5 });
  
  console.log(`Found ${projects.items.length} projects:\n`);
  projects.items.forEach(p => {
    console.log(`  • ${p.name} (${p.status})`);
  });

  // Create an export (uncomment to test)
  // if (projects.items.length > 0) {
  //   const exp = await avala.exports.create({ 
  //     project: projects.items[0].uid 
  //   });
  //   console.log(`\n📦 Created export: ${exp.uid}`);
  // }
}

main().catch(console.error);
Save this example as example.ts, run npx tsx example.ts (after installing tsx), and watch it fetch your Avala data!

​
Error handling

The SDK throws typed errors for different failure scenarios: 
import Avala, { 
  AvalaError, 
  NotFoundError, 
  RateLimitError,
  AuthenticationError 
} from "@avala-ai/sdk";

const avala = new Avala();

try {
  const dataset = await avala.datasets.get("nonexistent-uid");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Dataset not found");
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof AvalaError) {
    console.log(`API error: ${error.message}`);
    console.log(`Status code: ${error.statusCode}`);
  } else {
    throw error; // Re-throw non-Avala errors
  }
}
All SDK errors extend AvalaError, which includes statusCode and body properties for debugging.

​
Rate limit information

Access rate limit details from the last API response: 
const datasets = await avala.datasets.list();

const rateLimit = avala.rateLimitInfo;
console.log(`Limit: ${rateLimit.limit}`);
console.log(`Remaining: ${rateLimit.remaining}`);
console.log(`Reset: ${rateLimit.reset}`);

​
Next steps

Explore resources

Discover all available resources: projects, exports, tasks, agents, and more

Advanced features

Learn about pagination, filtering, error handling, and more

Code examples

Browse practical examples for common use cases

API reference

View the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us