Create Exports

Local Export

The SDK provides functionality to export project data locally. This feature allows you to export annotations in various formats for further analysis or backup purposes. The export created will be available in the exports section of Labellerr dashboard. Here is where you can find the export in our tool.

Acceptable values:

statuses: File workflow statuses to include in the export
- None, 'assigned', 'review', 'r_assigned', 'client_review', 'cr_assigned', 'accepted', 'rejected', 'client_rejected', 'skipped', 'r_skipped', 'cr_skipped', 'critical', 'r_critical', 'cr_critical'
export_format: Output format for the exported data
- 'json', 'coco_json', 'csv', 'png'

What do these status values mean?

File Status Definitions:

None - Unlabeled or pre-annotated files that haven’t entered the annotation workflow yet
assigned - Files assigned to an annotator, annotation work is in progress
review - Files ready for review (passed annotation phase)
r_assigned - Files assigned to a reviewer, review work is in progress
client_review - Files that have passed internal review and are now in client review stage
cr_assigned - Files assigned for client review, client review work is in progress
accepted - Files that have completed all stages and passed by client (final approved state)
rejected - Files rejected by the reviewer during review stage
client_rejected - Files rejected by the client during client review stage
skipped - Files skipped by the annotator during annotation stage
r_skipped - Files skipped by the reviewer during review stage
cr_skipped - Files skipped by the client during client review stage
critical - Files skipped 2 times in annotation stage, will go into blocked state
r_critical - Files skipped 2 times in review stage, will go into blocked state
cr_critical - Files skipped 2 times in client review stage, will go into blocked state

Tip: You can include multiple statuses in your export to capture files at different stages of your annotation workflow.

Example Usage:

Local Export Example

from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import CreateExportParams
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # Create export configuration using CreateExportParams
    export_config = CreateExportParams(
        export_name="Weekly Export",
        export_description="Export of all accepted annotations",
        export_format="coco_json",
        statuses=['review', 'r_assigned','client_review', 'cr_assigned','accepted']
    )
    
    # Create export
    export = project.create_export(export_config)
    print(f"Local export created successfully. Export ID: {export.report_id}")
    
    # Optionally wait for completion
    export.status()  # Polls until export is complete
    
except LabellerrError as e:
    print(f"Local export creation failed: {str(e)}")

Note: The export process creates a downloadable file link of your project’s annotations based on the specified status filters. This is useful for backup purposes or when you need to process the annotations offline.

S3 Export

The SDK also provides functionality to export project data directly to AWS S3 buckets. This feature allows you to export annotations in various formats directly to your S3 storage for automated workflows, backup, or integration with other systems. The export created will be available in the exports section of Labellerr dashboard. Here is where you can find the export in our tool.

Prerequisites:

Before creating an S3 export, you need to:

Create an AWS S3 connection using your AWS credentials
Get the connection_id from the created connection

Example Usage:

S3 Export Example

from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.connectors import LabellerrS3Connection
from labellerr.core.schemas import AWSConnectionParams, CreateExportParams
from labellerr.core.exceptions import LabellerrError

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Create S3 connection
connection = LabellerrS3Connection.create_connection(
    client=client,
    params=AWSConnectionParams(
        aws_access_key="your_aws_access_key",
        aws_secrets_key="your_aws_secret_key",
        name="S3 Export Connection",
        description="Connection for exporting annotations to S3"
    )
)

# Create S3 export
project = LabellerrProject(client=client, project_id='your_project_id')
export = project.create_export(
    CreateExportParams(
        export_name="S3 Weekly Export",
        export_description="Export of all accepted annotations to S3",
        export_format="coco_json",
        statuses=['review', 'r_assigned', 'client_review', 'cr_assigned', 'accepted'],
        export_destination="s3",
        connection_id=connection.connection_id,
        export_folder_path="bucket_name/path/to/folder/"  # trailing slash is important
    )
)

print(f"Export ID: {export.report_id}")
export.status()  # Poll until completion

Important Notes:

The export_folder_path should follow the pattern: bucket_name/path/to/folder/ (the trailing slash is important)
Make sure your AWS credentials have write permissions to the specified S3 bucket
You can reuse the same connection_id for multiple exports without creating a new connection each time
The export will be uploaded directly to your S3 bucket at the specified path

List All Exports

The SDK provides functionality to retrieve all exports associated with a project. This method returns both completed and in-progress exports, making it easy to track and manage your export history.

Example Usage:

List All Exports Example

from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # List all exports for the project
    exports = project.list_exports()
    
    print(f"Completed exports: {len(exports.completed)}")
    print(f"In-progress exports: {len(exports.in_progress)}")
    
    # Access individual completed exports
    for export in exports.completed:
        print(f"Export ID: {export.get('report_id')}")
        print(f"  Name: {export.get('export_name')}")
        print(f"  Status: {export.get('export_status')}")
        print(f"  Created: {export.get('created_at')}")
    
    # Access in-progress exports
    for export in exports.in_progress:
        print(f"In-progress Export ID: {export.get('report_id')}")
        print(f"  Name: {export.get('export_name')}")
        
except LabellerrError as e:
    print(f"Failed to list exports: {str(e)}")

Response Structure: The list_exports() method returns an ExportsListResponse object with two properties:

completed: List of all completed exports
in_progress: List of all exports currently being processed

Use Cases:

Track export history for a project
Find specific export IDs for status checks or downloads
Monitor ongoing export operations
Audit export activities
Automate export management workflows

Incremental Export with Timestamp Filtering

New Feature: Filter files based on their last updated time to create incremental exports!

You can now filter files based on their last updated timestamp when creating exports. This powerful feature enables incremental backups where only files modified after a specific time are exported, significantly reducing export size and processing time.

Key Features:

Timestamp Format: Unix timestamp in milliseconds
Filter Criteria: Files updated after the specified timestamp
Works with: Both local and S3 export destinations
Optional Parameter: When not provided, all files matching status criteria are exported

Example Usage - Incremental Local Export:

Incremental Export Example

from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import CreateExportParams
from labellerr.core.exceptions import LabellerrError
import time

# Initialize the client
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project = LabellerrProject(client=client, project_id='your_project_id')

# Calculate timestamp for 7 days ago (in milliseconds)
seven_days_ago = int((time.time() - 7*24*60*60) * 1000)

try:
    # Create export with timestamp filter
    export_config = CreateExportParams(
        export_name="Weekly Incremental Export",
        export_description="Export files updated in last 7 days",
        export_format="coco_json",
        statuses=['review', 'accepted'],
        updated_after_timestamp=seven_days_ago  # Only files updated after this time
    )
    
    export = project.create_export(export_config)
    print(f"Export created with ID: {export.report_id}")
    
    # Wait for export to complete
    final_status = export.status()
    print(f"Export completed: {final_status}")
    
except LabellerrError as e:
    print(f"Export creation failed: {str(e)}")

Example Usage - Incremental S3 Export:

Incremental S3 Export Example

from labellerr.core.schemas import CreateExportParams, ExportDestination
from datetime import datetime
import time

# Get timestamp for midnight today (in milliseconds)
today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
today_midnight = int(today.timestamp() * 1000)

# Create incremental S3 export
export_config = CreateExportParams(
    export_name="Daily Incremental S3 Export",
    export_description="Export only files modified today",
    export_format="json",
    statuses=['accepted'],
    export_destination=ExportDestination.S3,
    connection_id="your_s3_connection_id",
    export_folder_path="bucket_name/exports/daily/",
    updated_after_timestamp=today_midnight  # Only files updated today
)

export = project.create_export(export_config)
print(f"S3 incremental export started: {export.report_id}")

Practical Use Cases:

Incremental Backups

Export only files modified since your last backup, reducing storage and bandwidth

Daily/Weekly Exports

Automate exports for specific time windows (last 24 hours, last week, etc.)

Change Tracking

Monitor and export recently modified annotations for quality control

Workflow Automation

Create automated pipelines that process only recent changes

Important Notes:

The timestamp must be in milliseconds (multiply seconds by 1000)
The filter is based on the file’s “last updated time” in the system
Combines with status filters - only files matching both criteria are exported
Works seamlessly with both local and S3 export destinations

Timestamp Conversion Examples:

import time
from datetime import datetime, timedelta

# Current time in milliseconds
now_ms = int(time.time() * 1000)

# 24 hours ago
yesterday = int((time.time() - 24*60*60) * 1000)

# Specific date and time
specific_date = datetime(2024, 12, 17, 0, 0, 0)
specific_timestamp = int(specific_date.timestamp() * 1000)

# Last Monday midnight
today = datetime.now()
days_since_monday = (today.weekday() - 0) % 7
last_monday = today - timedelta(days=days_since_monday)
last_monday_midnight = last_monday.replace(hour=0, minute=0, second=0, microsecond=0)
last_monday_ms = int(last_monday_midnight.timestamp() * 1000)

Check Export Status

This method allows users to check the export status of a previously triggered export task (both local and S3 exports). The status will indicate whether the export is still processing, completed, or failed. For local exports, if successful, the function also sends the downloadable file link URL with its expiration time and status. For S3 exports, it indicates when the export has been successfully uploaded to your S3 bucket.

Example Usage :

Check Export Status Example

from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Example input
project_id = 'your_project_id'
report_ids = ['export_report_id_1', 'export_report_id_2']

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # Check export status
    status = project.check_export_status(
        report_ids=report_ids
    )
    
    print(status)
except LabellerrError as e:
    print(f"Failed to check export status: {str(e)}")

Fetch Export Download URL

This endpoint is used to fetch the downloadable link for a previously created local export using the export’s UUID and report ID. The response includes a signed URL from which the export file can be downloaded with the time left to expire. Note: This method is only applicable for local exports. For S3 exports, the files are directly uploaded to your S3 bucket at the specified path.

Example Usage :

Fetch Download URL Example

from labellerr.client import LabellerrClient
from labellerr.core.exceptions import LabellerrError
import uuid

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'
report_ids = ['export_report_id']  # make sure it is a list
request_uuid = str(uuid.uuid4())

try:
    download_url = client.fetch_download_url(
        project_id=project_id,
        uuid=request_uuid,
        export_id=report_ids[0]
    )
    print(f"Download URL: {download_url}")
except LabellerrError as e:
    print(f"Failed to fetch download URL: {str(e)}")

Export Management Features Summary

List All Exports

Retrieve all completed and in-progress exports for your project

Incremental Exports

Filter files by timestamp for efficient incremental backups

Local Export

Export annotations to downloadable files

S3 Export

Export directly to AWS S3 buckets

Export Status

Monitor export progress with automatic download URLs

Download URLs

Fetch signed download links for completed exports

Quick Reference

Export Formats

Format	Description	Use Case
`json`	Standard JSON format	General purpose, easy to parse
`coco_json`	COCO dataset format	Computer vision, object detection
`csv`	Comma-separated values	Spreadsheet analysis, reports
`png`	Image format	Visual verification, masks

Export Statuses

Status	Description
`review`	Files in review stage
`r_assigned`	Files assigned for review
`client_review`	Files in client review
`cr_assigned`	Files assigned for client review
`accepted`	Accepted/completed files

Common Timestamp Calculations

import time
from datetime import datetime, timedelta

# Last 24 hours
yesterday = int((time.time() - 86400) * 1000)

# Last 7 days
week_ago = int((time.time() - 7*86400) * 1000)

# Last 30 days
month_ago = int((time.time() - 30*86400) * 1000)

# Start of today
today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
today_start = int(today.timestamp() * 1000)

# Start of this week (Monday)
days_since_monday = (datetime.now().weekday() - 0) % 7
week_start = datetime.now() - timedelta(days=days_since_monday)
week_start = week_start.replace(hour=0, minute=0, second=0, microsecond=0)
week_start_ms = int(week_start.timestamp() * 1000)

SDK Documentation

MCP Server

Local Export

Acceptable values:

Example Usage:

S3 Export

Prerequisites:

Example Usage:

List All Exports

Example Usage:

Incremental Export with Timestamp Filtering

Key Features:

Example Usage - Incremental Local Export:

Example Usage - Incremental S3 Export:

Practical Use Cases:

Incremental Backups

Daily/Weekly Exports

Change Tracking

Workflow Automation

Check Export Status

Example Usage :

Fetch Export Download URL

Example Usage :

Export Management Features Summary

List All Exports

Incremental Exports

Local Export

S3 Export

Export Status

Download URLs

Quick Reference

Export Formats

Export Statuses

Common Timestamp Calculations

SDK Documentation

MCP Server

​Local Export

​Acceptable values:

​Example Usage:

​S3 Export

​Prerequisites:

​Example Usage:

​List All Exports

​Example Usage:

​Incremental Export with Timestamp Filtering

​Key Features:

​Example Usage - Incremental Local Export:

​Example Usage - Incremental S3 Export:

​Practical Use Cases:

Incremental Backups

Daily/Weekly Exports

Change Tracking

Workflow Automation

​Check Export Status

​Example Usage :

​Fetch Export Download URL

​Example Usage :

​Export Management Features Summary

List All Exports

Incremental Exports

Local Export

S3 Export

Export Status

Download URLs

​Quick Reference

​Export Formats

​Export Statuses

​Common Timestamp Calculations

Local Export

Acceptable values:

Example Usage:

S3 Export

Prerequisites:

Example Usage:

List All Exports

Example Usage:

Incremental Export with Timestamp Filtering

Key Features:

Example Usage - Incremental Local Export:

Example Usage - Incremental S3 Export:

Practical Use Cases:

Check Export Status

Example Usage :

Fetch Export Download URL

Example Usage :

Export Management Features Summary

Quick Reference

Export Formats

Export Statuses

Common Timestamp Calculations