List Tasks

Retrieve a paginated list of tasks with optional filtering by date range

Endpoint

GET /api/v1/tasks

Authentication

This endpoint requires API key authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

page · integer

Page number for pagination (1-indexed). If provided, limit is required.

limit · integer

Number of tasks to return per page. Required when page is provided.

start · string

Start date for filtering tasks (ISO 8601 format). Only tasks created on or after this date will be returned.

end · string

End date for filtering tasks (ISO 8601 format). Only tasks created on or before this date will be returned.

base64_urls · boolean · default: false

Whether to return base64 encoded URLs. If false, URLs will be returned as presigned URLs.

include_chunks · boolean · default: false

Whether to include chunks in the output response for each task. Set to true to get full task details (can increase response size significantly).

Response

Returns an array of task objects. Each task has the same structure as the Get Task response.

tasks · array

Array of task objects, each containing:

Show properties

task_id · string

Unique identifier for the task

status · enum

Task status: Starting, Processing, Succeeded, Failed, or Cancelled

created_at · string

Creation timestamp (ISO 8601)

started_at · string

Processing start timestamp (ISO 8601)

finished_at · string

Completion timestamp (ISO 8601)

expires_at · string

Expiration timestamp (ISO 8601)

message · string

Status message or error description

task_url · string

Presigned URL of the task

configuration · object

Complete task configuration including input file URL and all processing settings

output · object

Output data (only included if include_chunks=true and status is Succeeded)

Status Codes

• 200: Tasks retrieved successfully
• 400: Bad request (limit is required when page is provided)
• 500: Internal server error

Examples

cURL (Basic)

curl -X GET "https://api.chunkr.ai/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering and Pagination

Date Range Filtering

Filter tasks by creation date using start and end parameters:

# Last 24 hours
params = {
    "start": (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z",
    "end": datetime.utcnow().isoformat() + "Z"
}

# Specific month
params = {
    "start": "2024-03-01T00:00:00Z",
    "end": "2024-03-31T23:59:59Z"
}

Pagination

When using pagination:

• Pages are 1-indexed (first page is page=1)
• limit is required when page is specified
• If a page has fewer items than limit, you’ve reached the last page
• Without page and limit, all tasks are returned (use with caution for large datasets)

Performance Considerations

1. include_chunks: Setting this to true significantly increases response size and processing time. Only use when you need full task details.

2. Pagination: Always use pagination for large result sets to avoid timeouts and memory issues.

3. Date Filtering: Narrow your date range to improve query performance.

4. Limit Size: Recommended limit values:

   • Small limit (10-50): For UI pagination
   • Medium limit (50-100): For data processing
   • Large limit (100+): Only when necessary and with pagination

Common Use Cases

Monitor Recent Tasks

# Get tasks from the last hour
params = {
    "start": (datetime.utcnow() - timedelta(hours=1)).isoformat() + "Z",
    "limit": 100
}

Find Failed Tasks

tasks = requests.get(url, headers=headers).json()
failed = [t for t in tasks if t['status'] == 'Failed']
print(f"Failed tasks: {len(failed)}")

Export Task Summary

import csv

tasks = get_all_tasks(api_key)

with open('tasks.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['Task ID', 'Status', 'Created', 'Finished'])
    
    for task in tasks:
        writer.writerow([
            task['task_id'],
            task['status'],
            task['created_at'],
            task.get('finished_at', 'N/A')
        ])

Cleanup Old Tasks

# Find and delete tasks older than 30 days
old_date = (datetime.utcnow() - timedelta(days=30)).isoformat() + "Z"

params = {"end": old_date}
tasks = requests.get(url, headers=headers, params=params).json()

for task in tasks:
    if task['status'] in ['Succeeded', 'Failed', 'Cancelled']:
        delete_url = f"https://api.chunkr.ai/api/v1/task/{task['task_id']}"
        requests.delete(delete_url, headers=headers)
        print(f"Deleted task {task['task_id']}")

Error Handling

import requests

def list_tasks_safe(api_key, page=None, limit=None):
    """List tasks with proper error handling"""
    url = "https://api.chunkr.ai/api/v1/tasks"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    params = {}
    if page is not None:
        if limit is None:
            return {"error": "limit is required when page is provided"}
        params["page"] = page
        params["limit"] = limit
    
    try:
        response = requests.get(url, headers=headers, params=params, timeout=30)
        
        if response.status_code == 200:
            return {"success": True, "tasks": response.json()}
        elif response.status_code == 400:
            return {"error": response.text}
        else:
            return {"error": f"HTTP {response.status_code}: {response.text}"}
            
    except requests.exceptions.Timeout:
        return {"error": "Request timed out"}
    except requests.exceptions.RequestException as e:
        return {"error": f"Network error: {str(e)}"}

Related Endpoints

• Get Task - Get detailed information about a specific task
• Create Task - Create a new task
• Delete Task - Delete tasks from the list