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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deepomatic.com/deepomatic-api-v0.7/tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.