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.
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 minutes 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

Wait until the task status is finished or error. This makes the request block until the task has been completed. Requires the task.read scope.

We do not recommend using this for long running jobs (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 job 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.

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://api.cloudconvert.com/v2/tasks/{ID}/wait

Example Request

$ curl -g "https://api.cloudconvert.com/v2/tasks/c85f3ca9-164c-4e89-8ae2-c08192a7cb08/wait" \
       -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.

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"