Export tasks

An export task collects the history of selected points on one device into a CSV or JSON file. Tasks run in the background: create a task, wait for status to reach completed, then request a short-lived download URL.

Method	Endpoint	Description
GET	/api/v2/data-download-tasks/	List export tasks in the organization
GET	/api/v2/projects/{project_id}/data-download-tasks/	List export tasks in a project
GET	/api/v2/projects/{project_id}/data-download-tasks/options/	Retrieve export limits
POST	/api/v2/projects/{project_id}/data-download-tasks/	Create an export task
GET	/api/v2/projects/{project_id}/data-download-tasks/{id}/	Retrieve an export task
POST	/api/v2/projects/{project_id}/data-download-tasks/{id}/cancel/	Cancel an export task
POST	/api/v2/projects/{project_id}/data-download-tasks/{id}/retry/	Retry an export task
GET	/api/v2/projects/{project_id}/data-download-tasks/{id}/download/	Get a download URL
DELETE	/api/v2/projects/{project_id}/data-download-tasks/{id}/	Delete an export task

Tasks cannot be edited; PUT and PATCH return 405.

Visibility

Manager and Owner callers see every task in the projects they can access. Read-only and Operator callers see only tasks created with their own credentials. Operators can cancel, retry, download, and delete only their own tasks. The can_* fields on each task report what the caller can do.

The export task object

{
  "id": 15,
  "task_key": "6f1c2a7e-3b9d-4c55-9a51-2f0f6c7d8e90",
  "organization_id": 3,
  "project_id": "proj_AbCdEfGhIj",
  "project_name": "Greenhouse Alpha",
  "device_id": 42,
  "device_agri_id": "d-1000-abcd",
  "name": "ColdRoom_2factors_20260201-20260203",
  "format": "csv",
  "start_time": 1769904000,
  "end_time": 1770076800,
  "factor_count": 2,
  "status": "completed",
  "status_display": "Completed",
  "error_code": "",
  "error_msg": null,
  "estimated_raw_count": 5760,
  "progress_stage": "",
  "processed_row_count": 2880,
  "row_count": 2880,
  "file_size": 183204,
  "create_time": "2026-02-03T08:00:00Z",
  "updated_time": "2026-02-03T08:01:12Z",
  "started_at": "2026-02-03T08:00:05Z",
  "completed_at": "2026-02-03T08:01:12Z",
  "expires_at": "2026-05-04T08:01:12Z",
  "can_cancel": false,
  "can_retry": false,
  "can_download": true,
  "can_delete": true,
  "project_access_removed": false
}

Field	Type	Description
id	integer	Task ID
task_key	string	Task UUID
project_id, project_name	string	Project at creation time; kept after the project is deleted
device_id, device_agri_id	integer, string	Exported device
name	string	File name stem
format	string	csv or json
start_time, end_time	integer	Export range in Unix seconds
factor_count	integer	Number of points exported
status	string	See Task status
error_code, error_msg	string | null	Failure details
estimated_raw_count, processed_row_count, row_count	integer | null	Progress counters
file_size	integer | null	File size in bytes
create_time, updated_time, started_at, completed_at	string | null	Lifecycle times
expires_at	string | null	Time the file is removed
can_cancel, can_retry, can_download, can_delete	boolean	Actions available to the caller
project_access_removed	boolean	true when the caller lost access to the project. Such tasks show only id, format, status, status_display, create_time, and the can_* fields.

Retrieve an export task and Create an export task also return factor_ids (the exported point agri_id values) and field_mapping (column headers by agri_id).

Task status

Status	Meaning
pending	Created, waiting to be queued
queued	Queued for the export worker
exporting	Export in progress
cancelling	Cancel requested while exporting
completed	File ready to download
failed	Export failed; see error_code and error_msg
cancelled	Cancelled

List organization export tasks

GET /api/v2/data-download-tasks/

Returns visible tasks across the organization, newest first, one page at a time.

Authentication

Bearer token. Minimum role: Read-only.

Query parameters

Name	Type	Required	Description
project_id	string	No	Return tasks of one project
status	string	No	Return tasks in one status
page	integer	No	Page number. Default 1.
page_size	integer	No	Tasks per page, 1–100. Default 50.

Example request

curl 'https://dl.yengear.com/api/v2/data-download-tasks/?status=completed&page_size=20' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example response

{
  "success": true,
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{ "id": 15, "status": "completed", "name": "ColdRoom_2factors_20260201-20260203" }],
    "has_active_tasks": false
  },
  "error": null
}

has_active_tasks is true while a matching task is pending, queued, exporting, or cancelling. next and previous are absolute URLs.

Responses

• 200: A page of export task objects.
• 400: Unknown status, or a non-integer page or page_size.

List project export tasks

GET /api/v2/projects/{project_id}/data-download-tasks/

Returns visible tasks of one project, newest first.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier

Responses

• 200: Array of export task objects, not paginated.
• 403: The project is outside the token's scope.
• 404: No such project.

Retrieve export limits

GET /api/v2/projects/{project_id}/data-download-tasks/options/

Returns the formats and limits that apply to new tasks.

Authentication

Bearer token. Minimum role: Read-only.

Example response

{
  "success": true,
  "data": {
    "formats": ["csv", "json"],
    "default_format": "csv",
    "max_factor_count": 200,
    "max_range_days": 90,
    "max_raw_records": 1000000,
    "file_retention_days": 90,
    "presigned_url_seconds": 60
  },
  "error": null
}

Field	Description
max_factor_count	Points per task
max_range_days	Longest export range
max_raw_records	Raw records per task
file_retention_days	Days a finished file is kept
presigned_url_seconds	Lifetime of a download URL

Read limits from this endpoint instead of hard-coding them.

Create an export task

POST /api/v2/projects/{project_id}/data-download-tasks/

Creates an export task for points on one device and queues it.

Authentication

Bearer token. Minimum role: Operator.

Headers

Name	Required	Description
Idempotency-Key	No	Up to 64 characters. Repeating a request with the same key returns the existing task with 200 instead of creating another.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier

Request body

Name	Type	Required	Description
device_id	integer	Yes	Device ID in the project
factors	string[]	Yes	Point agri_id values of that device. Duplicates are removed.
start_time	integer	Yes	Range start, Unix seconds
end_time	integer	Yes	Range end, Unix seconds; not earlier than start_time
format	string	No	csv (default) or json
name	string	No	File name stem, up to 128 characters. Generated from the device name, point count, and dates when omitted.

Example request

curl -X POST 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/data-download-tasks/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: coldroom-2026-02-01' \
  -d '{
    "device_id": 42,
    "factors": ["d-1000-abcd-1-00", "d-1000-abcd-1-10"],
    "start_time": 1769904000,
    "end_time": 1770076800,
    "format": "csv"
  }'

Responses

• 201: The new export task object, with factor_ids and field_mapping.
• 200: A task with the same Idempotency-Key already exists; it is returned unchanged.
• 400: Validation error. error.reason is one of INVALID_DEVICE, INVALID_FACTORS, TOO_MANY_FACTORS, INVALID_TIME_RANGE, EXPORT_RANGE_TOO_LARGE, INVALID_FORMAT, INVALID_NAME, or INVALID_IDEMPOTENCY_KEY.
• 403 INVALID_FACTORS: A point is not on the selected device.
• 404 DEVICE_NOT_FOUND: The device is not in the project.
• 503 EXPORT_TEMPORARILY_UNAVAILABLE: The export service is unavailable.

Retrieve an export task

GET /api/v2/projects/{project_id}/data-download-tasks/{id}/

Returns one task, including factor_ids and field_mapping. Poll this endpoint to follow progress.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
project_id	string	Yes	Project identifier
id	integer	Yes	Task ID

Responses

• 200: The export task object.
• 404: The task does not exist or is not visible to the caller.

Cancel an export task

POST /api/v2/projects/{project_id}/data-download-tasks/{id}/cancel/

Cancels a task. A pending or queued task becomes cancelled; an exporting task becomes cancelling until the worker stops.

Authentication

Bearer token. Minimum role: Operator.

Responses

• 200: The updated export task object.
• 409 TASK_NOT_CANCELLABLE: The task has already finished.

Retry an export task

POST /api/v2/projects/{project_id}/data-download-tasks/{id}/retry/

Queues a failed task again.

Authentication

Bearer token. Minimum role: Operator.

Responses

• 200: The updated export task object, with status pending.
• 409 TASK_NOT_RETRYABLE: Only failed tasks can be retried.

Get a download URL

GET /api/v2/projects/{project_id}/data-download-tasks/{id}/download/

Returns a signed URL for the finished file. The URL expires after presigned_url_seconds (60 seconds by default), so request it right before downloading.

Authentication

Bearer token. Minimum role: Operator. The organization's plan must be active.

Example request

curl 'https://dl.yengear.com/api/v2/projects/proj_AbCdEfGhIj/data-download-tasks/15/download/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example response

{
  "success": true,
  "data": { "download_url": "https://example-bucket.s3.amazonaws.com/exports/..." },
  "error": null
}

Responses

• 200: data.download_url holds the signed URL.
• 403: Role below Operator, or the plan is read-only.
• 404 EXPORT_FILE_MISSING: The file no longer exists in storage.
• 409 EXPORT_FILE_MISSING: The task is not completed.
• 410 EXPORT_FILE_EXPIRED: The file passed its retention period.
• 503 EXPORT_TEMPORARILY_UNAVAILABLE: File storage is unavailable.

Delete an export task

DELETE /api/v2/projects/{project_id}/data-download-tasks/{id}/

Deletes a finished task and its file from storage.

Authentication

Bearer token. Minimum role: Operator.

Responses

• 204: Task and file deleted.
• 409 TASK_NOT_DELETABLE: Only completed, failed, or cancelled tasks can be deleted.
• 503 EXPORT_TEMPORARILY_UNAVAILABLE: The file could not be removed from storage.

Related

• List point history
• Data export in the console