> For the complete documentation index, see [llms.txt](https://docs.deepomatic.com/deepomatic-api-v0.7/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.deepomatic.com/deepomatic-api-v0.7/tasks.md).

# Tasks

## Task object

### Definition

Some endpoints do not return a direct response. Instead they return a `task_id` which will contain the results once ready. In most cases you will need to [get the task](/deepomatic-api-v0.7/tasks.md#get-single-task-status) until the status is not `pending`. The status will then either be:

* `success`: in which case you can read the `data` field to access the expected response.
* `error`: in which case the `error` field will contain an error message and the `data` field will be null.

| Attribute     | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| id            | string | The task ID                                                          |
| status        | string | The task status, either `"pending"`, `"success"`, or `"error"`       |
| error         | string | Defined in case of error, it is the error message                    |
| date\_created | string | The creation data timestamp                                          |
| date\_updated | string | The timestamp where status switched from "pending" to another status |
| data          | object | The response JSON of the endpoint that generated the task            |

### Response

{% code title="JSON" %}

```javascript
{
    "id": "269999729",
    "status": "success",
    "error": null,
    "date_created": "2018-03-10T20:38:12.818792Z",
    "date_updated": "2018-03-10T20:38:13.032942Z",
    "data": {
        "outputs": [
            {
                "labels": {
                    "discarded": [],
                    "predicted": [
                        {
                            "threshold": 0.025,
                            "label_id": 207,
                            "score": 0.952849746,
                            "label_name": "golden retriever"
                        }
                    ]
                }
            }
        ]
    },
    "subtasks": null
}
```

{% endcode %}

## Get single task status

### Definition

This endpoint retrieves the state of a given task.

{% tabs %}
{% tab title="cURL" %}

```bash
TASK_ID=123
curl https://api.deepomatic.com/v0.7/tasks/${TASK_ID} \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
```

{% endtab %}

{% tab title="Python" %}

```python
client.Task.retrieve({TASK_ID})
```

{% endtab %}
{% endtabs %}

### Arguments

| Parameter | Type   | Default | Description |
| --------- | ------ | ------- | ----------- |
| task\_id  | string |         | The task ID |

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.deepomatic.com/v0.7/tasks/269999729 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
```

{% endtab %}

{% tab title="Python" %}

```r
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

client.Task.retrieve(269999729)
```

{% endtab %}
{% endtabs %}

### Response

It returns a [task object](/deepomatic-api-v0.7/tasks.md#task-object).

{% code title="JSON" %}

```javascript
{
    "id": "269999729",
    "status": "success",
    "error": null,
    "date_created": "2018-03-10T20:38:12.818792Z",
    "date_updated": "2018-03-10T20:38:13.032942Z",
    "data": {
        "outputs": [
            {
                "labels": {
                    "discarded": [],
                    "predicted": [
                        {
                            "threshold": 0.025,
                            "label_id": 207,
                            "score": 0.952849746,
                            "label_name": "golden retriever"
                        }
                    ]
                }
            }
        ]
    },
    "subtasks": null
}
```

{% endcode %}

## Get multiple task status

### Definition

Retrieve several tasks status given their IDs.

{% tabs %}
{% tab title="cURL" %}

```bash
GET https://api.deepomatic.com/v0.7/tasks
```

{% endtab %}

{% tab title="Python" %}

```python
tasks = client.Task.list(task_ids=[...])
```

{% endtab %}
{% endtabs %}

### Arguments

| Parameter | Type          | Default | Description                             |
| --------- | ------------- | ------- | --------------------------------------- |
| task\_ids | array(string) |         | The task IDs as a JSON array of strings |

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.deepomatic.com/v0.7/tasks?task_ids=269999729&task_ids=269999730 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
```

{% endtab %}

{% tab title="Python" %}

```python
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

tasks = client.Task.list(task_ids=[269999729, 269999730])
```

{% endtab %}
{% endtabs %}

### Response

A paginated list of [task objects](/deepomatic-api-v0.7/tasks.md#task-object).

| Attribute | Type                                                       | Description                                                          |
| --------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
| count     | int                                                        | The total number of results.                                         |
| next      | string                                                     | The URL to the next page.                                            |
| previous  | string                                                     | The URL to the previous page.                                        |
| results   | array([object](/deepomatic-api-v0.7/tasks.md#task-object)) | A list of [task objects](/deepomatic-api-v0.7/tasks.md#task-object). |

{% code title="JSON" %}

```javascript
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "269999729",
            "status": "success",
            "error": null,
            "date_created": "2018-03-10T20:38:12.818792Z",
            "date_updated": "2018-03-10T20:38:13.032942Z",
            "data": {
                "outputs": [
                    {
                        "labels": {
                            "predicted": [
                                {
                                    "threshold": 0.025,
                                    "label_id": 207,
                                    "score": 0.952849746,
                                    "label_name": "golden retriever"
                                }
                            ],
                            "discarded": []
                        }
                    }
                ]
            },
            "subtasks": null
        },
        {
            "id": "269999730",
            "status": "success",
            "error": null,
            "date_created": "2018-03-10T20:39:47.346716Z",
            "date_updated": "2018-03-10T20:39:47.553246Z",
            "data": {
                "outputs": [
                    {
                        "labels": {
                            "predicted": [
                                {
                                    "threshold": 0.025,
                                    "label_id": 207,
                                    "score": 0.952849746,
                                    "label_name": "golden retriever"
                                }
                            ],
                            "discarded": []
                        }
                    }
                ]
            },
            "subtasks": null
        }
    ]
}
```

{% endcode %}