> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labellerr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Exports

> Learn how to use the Labellerr SDK to export project data locally or to AWS S3 in various formats, check export status, and fetch downloadable URLs.

### 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**](/actions/create-export)**.**

#### 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'`

<Accordion title="What do these status values mean?" icon="circle-info">
  **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.
</Accordion>

#### Example Usage:

```python Local Export Example lines icon="download" theme={"dark"}
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**](/actions/create-export)**.**

#### Prerequisites:

Before creating an S3 export, you need to:

1. Create an AWS S3 connection using your AWS credentials
2. Get the `connection_id` from the created connection

#### Example Usage:

```python S3 Export Example lines icon="cloud-arrow-up" theme={"dark"}
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:

```python List All Exports Example lines icon="list" theme={"dark"}
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

<Note>
  **New Feature**: Filter files based on their last updated time to create incremental exports!
</Note>

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:

```python Incremental Export Example lines icon="clock-rotate-left" theme={"dark"}
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:

```python Incremental S3 Export Example lines icon="cloud" theme={"dark"}
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:

<CardGroup cols={2}>
  <Card title="Incremental Backups" icon="floppy-disk">
    Export only files modified since your last backup, reducing storage and bandwidth
  </Card>

  <Card title="Daily/Weekly Exports" icon="calendar">
    Automate exports for specific time windows (last 24 hours, last week, etc.)
  </Card>

  <Card title="Change Tracking" icon="timeline">
    Monitor and export recently modified annotations for quality control
  </Card>

  <Card title="Workflow Automation" icon="robot">
    Create automated pipelines that process only recent changes
  </Card>
</CardGroup>

**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:**

```python theme={"dark"}
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 :

```python Check Export Status Example lines icon="magnifying-glass" theme={"dark"}
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 :

```python Fetch Download URL Example lines icon="link" theme={"dark"}
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

<CardGroup cols={2}>
  <Card title="List All Exports" icon="list" href="#list-all-exports">
    Retrieve all completed and in-progress exports for your project
  </Card>

  <Card title="Incremental Exports" icon="clock-rotate-left" href="#incremental-export-with-timestamp-filtering">
    Filter files by timestamp for efficient incremental backups
  </Card>

  <Card title="Local Export" icon="download" href="#local-export">
    Export annotations to downloadable files
  </Card>

  <Card title="S3 Export" icon="cloud" href="#s3-export">
    Export directly to AWS S3 buckets
  </Card>

  <Card title="Export Status" icon="magnifying-glass" href="#check-export-status">
    Monitor export progress with automatic download URLs
  </Card>

  <Card title="Download URLs" icon="link" href="#fetch-export-download-url">
    Fetch signed download links for completed exports
  </Card>
</CardGroup>

***

## 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

```python theme={"dark"}
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)
```

***