> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tasks
> Process large volumes of registry operations efficiently using the bulk API or ensure atomicity with bundle requests
Tasks are a grouping of operations that can be processed together in the registry. There are three common
ways tasks are created:
* **Bulk tasks**: Process large volumes of resource or relationship operations asynchronously.
* **Bundle tasks**: Apply resources and relationships atomically in a single transaction.
Bulk tasks are intended to be used for high-throughput operations where you need to create, update, or delete many resources or relationships efficiently.
Bundle tasks are useful when you need to ensure that a set of operations either all succeed or all fail together, maintaining data integrity.
## Overview
The task API workflow consists of two main steps:
1. **Submit a task request** - Send a batch of operations using the bulk endpoints. This returns a task ID.
2. **Check task status** - Monitor the progress and retrieve results using the task ID.
There is no way to retrieve the task ID after submitting a bulk request. Make sure to store it for later use!
### At a glance
| | **[Bundle API](/api-reference/bundle/bundle-resource-and-relationship-operations-to-be-processed)** | **Bulk API** ([Resources](/api-reference/bulk/bulk-create-upsert-or-delete-resources), [Relationships](/api-reference/bulk/bulk-create-upsert-or-delete-relationships)) |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use Case** | Multiple operations on [Resources](/explanation/data-model/data-sources#resource) and [Relationships](/explanation/data-model/data-sources#relationship) | Optimizing operations when dealing with large volumes. |
| **Execution** | Synchronous | Asynchronous |
| **Supported Operations** | `"CREATE"`,`"UPSERT"`, `"DELETE"` | `"CREATE"`,`"UPSERT"`, `"DELETE"` |
| **Atomic Transaction** | Yes | No |
| **Maximum Volume per Request** | 500 KB | 5 GB |
## Supported bulk operations
The registry supports bulk operations for both resources and relationships:
* **Resource operations**: `CREATE`, `UPSERT`, or `DELETE` multiple resources
* **Relationship operations**: `CREATE`, `UPSERT`, or `DELETE` multiple relationships
Both are very similar in structure, but the endpoints and payloads differ.
## Creating a bulk request
### Bulk resources
Use the [bulk resources endpoint](/api-reference/bulk/bulk-create-upsert-or-delete-resources) to process multiple resource operations:
```bash {collectForTests=bulkResourcesRequest} theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/resources/bulk" \
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{
"action": "CREATE",
"create": {
"type": "patient",
"id": "patient-123",
"data": {
"name": [
{
"given": [
"John"
],
"family": "Doe"
}
]
}
}
}
]
}'
```
```json {collectForTests=bulkResourcesResponse} theme={null}
{
"status": "ACCEPTED",
"taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}
```
### Bulk relationships
Use the [bulk relationships endpoint](/api-reference/bulk/bulk-create-upsert-or-delete-relationships) to process multiple relationship operations:
```bash {collectForTests=bulkRelationshipsRequest} theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/relationships/bulk" \\
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"operations": [
{
"action": "CREATE",
"create": {
"type": "treats",
"from": {
"type": "practitioner",
"id": "doctor-123"
},
"to": {
"type": "patient",
"id": "patient-123"
},
"data": {}
}
}
]
}'
```
```json {collectForTests=bulkRelationshipsResponse} theme={null}
{
"status": "ACCEPTED",
"taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}
```
## Bundle operations
Use the [bundle endpoint](/api-reference/bundle/bundle-resource-and-relationship-operations-to-be-processed) to process resources and relationships atomically.
If any operation in the bundle fails, none of the operations are applied.
```bash {collectForTests=bundleRequest} theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/bundle" \
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"resourceOperations": [
{
"action": "CREATE",
"create": {
"type": "patient",
"id": "patient-123",
"data": {
"name": [
{
"given": [
"John"
],
"family": "Doe"
}
]
}
}
}
],
"relationshipOperations": []
}'
```
## Response format
A successful bulk or bundle operation returns an `ACCEPTED` [status](/api-reference/bulk/bulk-create-upsert-or-delete-resources#response-status), meaning the task is processed asynchronously in the background.
```json {collectForTests=bundleResponse } theme={null}
{
"status": "ACCEPTED",
"taskId": "bd_30sSi7otihHAiRpJ8F1YLpw6kfn"
}
```
## Checking task status
Whether you submitted a bulk request or a bundle operation, you can check the status of the task and
eventually retrieve the results using the [task endpoint](/api-reference/task/get-a-task-from-the-registry).
```bash theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/sources/my-source/v1/tasks/{taskId}?withReceipts=true" \
-H "X-Clinia-API-Key: $CLINIA_TOKEN"
```
```json theme={null}
{
"id": "bulk_abc123",
"status": "SUCCESS",
"createdAt": "2024-01-15T10:00:00Z",
"completedAt": "2024-01-15T10:05:30Z",
"operationReceipts": [
{
"status": "SUCCESS",
"action": "CREATE",
"target": {
"targetType": "RESOURCE",
"type": "patient",
"id": "patient-123"
},
"receivedAt": "2024-01-15T10:00:01Z",
"processedAt": "2024-01-15T10:01:15Z"
}
]
}
```
### Task statuses
The overall status of the task represents the completion state of all operations in the bulk request. The [possible values](/api-reference/task/get-a-task-from-the-registry#response-status) are:
* `SUCCESS` - All the operations of the task completed successfully
* `PENDING` - At least one operation in the task is still pending
* `CANCELLED` - All the operations in the task were cancelled
* `FAILURE` - At least one operations failed or was cancelled
The `CANCELLED` status can only occur if the operation was cancelled by the system. There is currently
no way to cancel a task or an operation manually.
For instance, if two tasks are submitted to operate on the same record id, the later task will be
kept and the earlier one will be cancelled.