Tasks represent individual annotation or labeling jobs within Avala projects. They track work assignments, progress, and completion status.
Overview
A task is a unit of work assigned within a project. Tasks enable you to:
- Assign specific annotation jobs to team members
- Track progress and status of labeling work
- Organize work by task type and project
- Monitor completion and quality
Task structure
interface Task {
uid: string;
type: string | null;
name: string | null;
status: string | null;
project: string | null;
createdAt: string | null;
updatedAt: string | null;
}
Properties
Unique identifier for the task
Task type (e.g., ‘annotation’, ‘review’, ‘qa’)
Current task status (e.g., ‘pending’, ‘in_progress’, ‘completed’)
UID of the parent project
ISO 8601 timestamp of task creation
ISO 8601 timestamp of last update
Listing tasks
Retrieve tasks with optional filters:
const page = await avala.tasks.list({
project: 'proj_123',
status: 'completed',
limit: 50
});
for (const task of page.items) {
console.log(`${task.name}: ${task.status}`);
}
Filter options
Return only tasks belonging to a specific project:const tasks = await avala.tasks.list({
project: 'proj_abc123'
});
Return only tasks with a specific status:const tasks = await avala.tasks.list({
status: 'in_progress'
});
Use multiple filters together:const tasks = await avala.tasks.list({
project: 'proj_abc123',
status: 'completed',
limit: 100
});
let allTasks = [];
let cursor: string | null = null;
do {
const page = await avala.tasks.list({
limit: 100,
cursor: cursor || undefined
});
allTasks.push(...page.items);
cursor = page.nextCursor;
} while (cursor);
console.log(`Total tasks: ${allTasks.length}`);
Always check hasMore to determine if additional pages exist.
Getting a task
Retrieve detailed information about a specific task:
const task = await avala.tasks.get('task_uid_here');
console.log(`Task: ${task.name}`);
console.log(`Type: ${task.type}`);
console.log(`Status: ${task.status}`);
console.log(`Project: ${task.project}`);
Task lifecycle
Tasks progress through various status values:
Pending
Task is created but not yet started
In progress
Task is actively being worked on
Review
Task work is complete and awaiting review
Completed
Task has been finished and approved
Rejected
Task was rejected and needs rework
Common workflows
Monitor project tasks
Find incomplete tasks
Track task completion
List all task types
// Get all tasks for a project
const tasks = await avala.tasks.list({
project: 'proj_123'
});
// Count by status
const statusCounts = tasks.items.reduce((acc, task) => {
acc[task.status || 'unknown'] = (acc[task.status || 'unknown'] || 0) + 1;
return acc;
}, {} as Record<string, number>);
console.log(statusCounts);
// { pending: 5, in_progress: 3, completed: 12 }
// Get pending tasks
const pending = await avala.tasks.list({
status: 'pending'
});
// Get in-progress tasks
const inProgress = await avala.tasks.list({
status: 'in_progress'
});
const incomplete = pending.items.length + inProgress.items.length;
console.log(`${incomplete} tasks remaining`);
const task = await avala.tasks.get('task_123');
if (task.status === 'completed') {
console.log(`Task completed on ${task.updatedAt}`);
const createdDate = new Date(task.createdAt!);
const completedDate = new Date(task.updatedAt!);
const duration = completedDate.getTime() - createdDate.getTime();
console.log(`Duration: ${duration / 1000 / 60 / 60} hours`);
}
const tasks = await avala.tasks.list();
const types = new Set(
tasks.items.map(t => t.type).filter(Boolean)
);
console.log('Task types:', Array.from(types));
Integration with agents
Tasks can be automated using AI agents:
// Agents can target specific task types
interface Agent {
uid: string;
name: string;
taskTypes: string[];
project: string | null;
// ...
}
Configure agents to automatically process tasks of specific types within your projects.
interface CursorPage<Task> {
items: Task[];
nextCursor: string | null;
previousCursor: string | null;
hasMore: boolean;
}
Best practices
Filter by project
Always filter tasks by project UID for better organization and performance
Monitor status
Track task status to measure progress and identify bottlenecks
Use pagination
Handle pagination properly when working with large task lists
Track timestamps
Use createdAt and updatedAt to measure task duration and performance
Combine project and status filters to efficiently query specific subsets of tasks.
- Projects: Tasks belong to projects - see Projects
- Agents: Automate task processing with AI agents
- Quality Targets: Set quality standards for task completion