Tasks

Create tasks

Tasks can be created using their operation specific endpoint. For example, see the convert task documentation on how to create a task for converting files.

Typically, you create a job which contains multiple tasks (for example: importing the file from S3, converting it and exporting it to S3 again).

Show a task

Show a task. Requires the task.read scope.

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

Returns

Attributes
id string	The ID of the task.
job_id string	The Job ID the tasks 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 tasks. Depends on the operation type.
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 on the right).

Endpoint

GET https://api.cloudconvert.com/v2/tasks/{ID}

Example Request

$ curl -g "https://api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08?include=payload" \
       -H "Authorization: Bearer API_KEY"

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": "2016",
    "payload": {
      "input_format": "docx",
      "output_format": "pdf",
      "page_range": "1-2",
      "optimize_print": true
    },
    "result": {
      "files": [
        {
          "filename": "document.pdf"
        }
      ]
    }
  }
}

Wait for a task

The CloudConvert API is asynchronous by default. When starting a task, the API responds immediately and you either receive the completed task via webhook notification or via polling.

As alternative, there is a synchronous option which waits until the task status is finished or error. This makes the request block until the task has been completed. Requires the task.read scope.

Requires the task.read scope. Please note that the synchronous API uses a different base URL (https://sync.api.cloudconvert.com).

We do not recommend using this for long running tasks (e.g. video encodings). Your system might automatically time out requests if there is not data transferred for a longer time.

In general, please avoid to block your application until a CloudConvert tasks 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.

This endpoint was previously available at https://api.cloudconvert.com/v2/tasks/{ID}/wait. Please migrate to the new base URL (https://sync.api.cloudconvert.com) for the synchronous API. We will shutdown the old endpoint on 28.02.2023. Affected customers are notified via email automatically.

Returns

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

Endpoint

GET https://sync.api.cloudconvert.com/v2/tasks/{ID}

Example Request

$ curl -g "https://sync.api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08" \
       -H "Authorization: Bearer API_KEY"

Lists tasks

List all tasks with their status, payload and result. Requires the task.read scope.

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

Returns

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

Endpoint

GET https://api.cloudconvert.com/v2/tasks

Example Request

$ curl -g "https://api.cloudconvert.com/v2/tasks" \
       -H "Authorization: Bearer API_KEY"

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 a task

Cancel a task that is in status waiting or processing. Requires the task.write scope.

Returns

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

Endpoint

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

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08/cancel" \
       -H "Authorization: Bearer API_KEY"

Retry a task

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

Returns

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

Endpoint

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

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08/retry" \
       -H "Authorization: Bearer API_KEY"

Delete a task

Delete a task, including all data. Requires the task.write scope.

Tasks are deleted automatically 24 hours after they have ended.

Returns

An empty response with HTTP Code 204.

Endpoint

DELETE https://api.cloudconvert.com/v2/tasks/{ID}

Example Request

$ curl -X DELETE "https://api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08" \
       -H "Authorization: Bearer API_KEY"

List possible operations

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

Query Parameters
filter[operation] string, optional	The result will be filtered to include only possible operations with a matching operation name (e.g. `convert` or `optimize`).
filter[input_format] string, optional	The result will be filtered to include only possible conversions with a matching input format.
filter[output_format] string, optional	The result will be filtered to include only possible conversions with a matching output format.
filter[engine] string, optional	Filter result to only include conversions with a matching engine name.
filter[engine_version] string, optional	Filter result to only include conversions with a matching engine version.
alternatives boolean, optional	For some formats multiple alternative engines are available. If set to `true`, the result includes these alternative conversion types. Default to `false`.
include array, optional	Include `options` and/or `engine_versions` in the result.

Returns

The list of possible conversion types.

Attributes

operation string Name of the operation, such as convert, optimize or capture-website.

input_format string Format of the input file.

output_format string Format of the conversion result.

engine string Name of the engine.

credits integer The base amount of conversion credits this operation consumes.

options array Possible options for this conversion type. Available, if the include argument contains options.
Show child attributes

name string	Name of the option.
type string	Data type of the option: `string`, `boolean`, `integer`, `float`, `enum` or `dictionary`.
default string	Default value.
possible_values array	Possible values if the data type is `enum`.

engine_versions array Compatible engine versions for this conversion type. Available, if the include argument contains engine_versions.
Show child attributes

version string	Version of the engine.
default boolean	This is the default version.
latest boolean	This version is the latest one.
deprecated boolean	This version is deprecated.
experimental boolean	This version is experimental.

deprecated boolean This format is deprecated.

experimental boolean This format is experimental.

meta dictionary Meta attributes.

Endpoint

GET https://api.cloudconvert.com/v2/operations

Example Request

$ curl -g "https://api.cloudconvert.com/v2/operations?filter[input_format]=pdf&include=options"

Convert Files

Optimize Files

Archives

Capture Websites

Merge Files

Convert Files

Capture Websites

Optimize Files

Other APIs

Automate

Documentation

Tasks

Create tasks

Show a task

Returns

Endpoint

Example Request

Example Response

Wait for a task

Returns

Endpoint

Example Request

Lists tasks

Returns

Endpoint

Example Request

Example Response

Cancel a task

Returns

Endpoint

Example Request

Retry a task

Returns

Endpoint

Example Request

Delete a task

Returns

Endpoint

Example Request

List possible operations

Returns

Endpoint

Example Request