CloudConvertdocs
API Reference

Tasks

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

Create task

Tasks are created when creating a 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 documentation on how to create a job with a convert task for converting files.

Show task Async

Show a task status.

GEThttps://api.cloudconvert.com/v2/tasks/{ID}

This endpoint is asynchronous and immediately responds the task status, even if the task has not completed yet. There is also a synchronous version of this endpoint available.

Authentication

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

Query Parameters

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

Response

The task status:

id
string
The ID of the task.
job_id
string
The Job ID the task belongs to.
name
string
The name of the task. Only available if the task is part of a job.
operation
string
Name of the operation, for example convert or import/s3.
status
string
The status of the task. Is one of waiting, processing, finished or error.
message
string
The status message. Contains the error message if the task status is error.
code
string
The error code if the task status is error.
credits
integer
The amount of conversion credits the task consumed. Available when the status is finished.
created_at
string
ISO8601 timestamp of the creation of the task.
started_at
string
ISO8601 timestamp when the task started processing.
ended_at
string
ISO8601 timestamp when the task finished or failed.
depends_on_tasks
object
List of tasks that are dependencies for this task. Only available if the include parameter was set to depends_on_tasks.
retry_of_task_id
string
ID of the original task, if this task is a retry.
retries
array
List of tasks that are retries of this task. Only available if the include parameter was set to retries.
engine
string
Name of the engine.
engine_version
string
Version of the engine.
payload
object
Your submitted payload for the task. Depends on the operation type. Only available if the include parameter was set to payload.
result
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).

Example Response

{
  "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"
        }
      ]
    }
  }
}

Wait for task Sync

Wait until the task status is completed and return the task status. This is the synchronous version of the show task endpoint.

GEThttps://sync.api.cloudconvert.com/v2/tasks/{ID}
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 is beneficial in such cases.

Authentication

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

Response

The finished or failed task. You can find details about the task model response in the documentation about the show task endpoint.

List tasks

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

GEThttps://api.cloudconvert.com/v2/tasks

Authentication

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

Query Parameters

filter[job_id]
string
The result will be filtered to include only tasks for a specific Job ID.
filter[status]
string
The result will be filtered to include only tasks with a specific status (waiting, processing, finished or error).
filter[operation]
string
Filter result to only include tasks with a matching operation (for example convert or import/s3).
include
array
Include retries and/or depends_on_tasks in the result.
per_page
number
Number of tasks per page, defaults to 100.
page
number
The result page to show.

Response

The list of tasks. You can find details about the task model response in the documentation about the show task endpoint.

Example Response

{
  "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
  }
}

Cancel task

Cancel a task that is in status waiting or processing.

POSThttps://api.cloudconvert.com/v2/tasks/{ID}/cancel

Authentication

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

Response

The updated task. You can find details about the task model response in the documentation about the show task endpoint.

Retry task

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

POSThttps://api.cloudconvert.com/v2/tasks/{ID}/retry

Authentication

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

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.

Delete task

Delete a task, including all data.

DELETEhttps://api.cloudconvert.com/v2/tasks/{ID}

Tasks are deleted automatically 24 hours after they have ended.

Authentication

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

Response

An empty response with HTTP Code 204.

Jobs

Create, list, show, wait for and delete jobs.

Operations

List all possible operations, formats, engines and possible options.