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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.