# Tasks

> Create, list, show, wait for, cancel, retry and delete tasks.

## Create task

Tasks are created when [creating a job](https://cloudconvert.com/docs/raw/api-reference/jobs.md#create-job). A job typically contains multiple tasks (for example: importing the file from S3, converting it and exporting it to S3 again).

For example, see the [convert files](https://cloudconvert.com/docs/raw/operations/convert-files.md#convert-tasks) documentation on how to create a job with a `convert` task for converting files.

---

## Show task <badge color="success" label="Async" size="lg"></badge>

Show a task status.

<api-endpoint endpoint="tasks/{ID}" method="GET">

[https://api.cloudconvert.com/v2/tasks/{ID}](https://api.cloudconvert.com/v2/tasks/%7BID%7D)

</api-endpoint>

This endpoint is asynchronous and immediately responds the task status, even if the task has not completed yet. There is also a [synchronous version](#wait-for-task) of this endpoint available.

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Query Parameters

<field-group>
<field name="include" type="array">

Include `retries`, `depends_on_tasks`, `payload` and/or `job` in the result. Multiple include values are separated by `,`.

</field>
</field-group>

#### Response

The task status:

<field-group>
<field name="id" type="string">

The ID of the task.

</field>

<field name="job_id" type="string">

The Job ID the task belongs to.

</field>

<field name="name" type="string">

The name of the task. Only available if the task is part of a job.

</field>

<field name="operation" type="string">

Name of the operation, for example `convert` or `import/s3`.

</field>

<field name="status" type="string">

The status of the task. Is one of `waiting`, `processing`, `finished` or `error`.

</field>

<field name="message" type="string">

The status message. Contains the error message if the task status is `error`.

</field>

<field name="code" type="string">

The error code if the task status is `error`.

</field>

<field name="credits" type="integer">

The amount of conversion credits the task consumed. Available when the status is `finished`.

</field>

<field name="created_at" type="string">

ISO8601 timestamp of the creation of the task.

</field>

<field name="started_at" type="string">

ISO8601 timestamp when the task started processing.

</field>

<field name="ended_at" type="string">

ISO8601 timestamp when the task finished or failed.

</field>

<field name="depends_on_tasks" type="object">

List of tasks that are dependencies for this task. Only available if the `include` parameter was set to `depends_on_tasks`.

</field>

<field name="retry_of_task_id" type="string">

ID of the original task, if this task is a retry.

</field>

<field name="retries" type="array">

List of tasks that are retries of this task. Only available if the `include` parameter was set to `retries`.

</field>

<field name="engine" type="string">

Name of the engine.

</field>

<field name="engine_version" type="string">

Version of the engine.

</field>

<field name="payload" type="object">

Your submitted payload for the task. Depends on the operation type. Only available if the `include` parameter was set to `payload`.

</field>

<field name="result" type="object">

The result of the task. Depends on the operation type. Finished tasks always do have a `files` key with the names of the result files of the task (See the example below).

</field>
</field-group>

#### Example Response

<code-collapse name="Response">

```json
{
  "data": {
    "id": "c85f3ca9-164c-4e89-8ae2-c08192a7cb08",
    "job_id": "73df1e16-fd8b-47a1-a156-f197babde91a",
    "operation": "convert",
    "status": "processing",
    "credits": null,
    "message": null,
    "code": null,
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "ended_at": null,
    "depends_on_tasks": {
      "my-import-task": "x441E6HMhG"
    },
    "engine": "office",
    "engine_version": "2.1",
    "payload": {
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "result": {
      "files": [
        {
          "filename": "document.pdf"
        }
      ]
    }
  }
}
```

</code-collapse>

---

## Wait for task <badge color="error" label="Sync" size="lg"></badge>

Wait until the task status is completed and return the task status. This is the **synchronous** version of the [show task endpoint](#show-task).

<api-endpoint endpoint="tasks/{ID}" method="GET" :sync="true">

[https://sync.api.cloudconvert.com/v2/tasks/{ID}](https://sync.api.cloudconvert.com/v2/tasks/%7BID%7D)

</api-endpoint>

<warning>

We do not recommend using this for long running tasks (e.g. video encodings). Your network stack might automatically time out requests if there is not data transferred for a longer time. As a good practice, please avoid to block your application until a CloudConvert task completes. There might be cases in which we need to queue your task which results in longer processing times than usual. Using an asynchronous approach with [webhooks](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) is beneficial in such cases.

</warning>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Response

The finished or failed task. You can find details about the task model response in the documentation about the [show task endpoint](#show-task).

---

## List tasks

List all your tasks with their status, payload and result.

<api-endpoint endpoint="tasks" method="GET">

[https://api.cloudconvert.com/v2/tasks](https://api.cloudconvert.com/v2/tasks)

</api-endpoint>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Query Parameters

<field-group>
<field name="filter[job_id]" type="string">

The result will be filtered to include only tasks for a specific Job ID.

</field>

<field name="filter[status]" type="string">

The result will be filtered to include only tasks with a specific status (`waiting`, `processing`, `finished` or `error`).

</field>

<field name="filter[operation]" type="string">

Filter result to only include tasks with a matching operation (for example `convert` or `import/s3`).

</field>

<field name="include" type="array">

Include `retries` and/or `depends_on_tasks` in the result.

</field>

<field name="per_page" type="number">

Number of tasks per page, defaults to `100`, maximum `1000`.

</field>

<field name="page" type="number">

The result page to show.

</field>
</field-group>

#### Response

The list of tasks. You can find details about the task model response in the documentation about the [show task endpoint](#show-task).

#### Example Response

<code-collapse name="Response">

```json
{
  "data": [
    {
      "id": "73df1e16-fd8b-47a1-a156-f197babde91a",
      "operation": "convert",
      "status": "processing",
      "credits": null,
      "message": null,
      "code": null,
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": "2018-09-19T14:42:58+00:00",
      "ended_at": null,
      "payload": {},
      "result": null,
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/h451E6HMhG"
      }
    },
    {
      "id": "4d610226-5347-4522-b08a-d165b1dde6a0",
      "operation": "export/s3",
      "status": "waiting",
      "credits": null,
      "message": null,
      "code": null,
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": null,
      "ended_at": null,
      "payload": {},
      "result": null,
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/Xhrek8bGGq"
      }
    }
  ],
  "links": {
    "first": "https://api.cloudconvert.com/v2/tasks?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "https://api.cloudconvert.com/v2/tasks",
    "per_page": 100,
    "to": 2
  }
}
```

</code-collapse>

---

## Cancel task

Cancel a task that is in status `waiting` or `processing`.

<api-endpoint endpoint="tasks/{ID}/cancel" method="POST">

[https://api.cloudconvert.com/v2/tasks/{ID}/cancel](https://api.cloudconvert.com/v2/tasks/%7BID%7D/cancel)

</api-endpoint>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Response

The updated task. You can find details about the task model response in the documentation about the [show task endpoint](#show-task).

---

## Retry task

Create a new task, based on the payload of another task.

<api-endpoint endpoint="tasks/{ID}/retry" method="POST">

[https://api.cloudconvert.com/v2/tasks/{ID}/retry](https://api.cloudconvert.com/v2/tasks/%7BID%7D/retry)

</api-endpoint>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Response

The new task (with a new task ID). You can find details about the task model response in the documentation about the [show task endpoint](#show-task).

---

## Delete task

Delete a task, including all data.

<api-endpoint endpoint="tasks/{ID}" method="DELETE">

[https://api.cloudconvert.com/v2/tasks/{ID}](https://api.cloudconvert.com/v2/tasks/%7BID%7D)

</api-endpoint>

Tasks are deleted automatically 24 hours after they have ended.

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Response

An empty response with HTTP Code `204`.