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

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 because we need to turn off the old endpoint at some point.

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 minutes this operation consumes.
options array Possible options for this conversion type. Available, if the include argument contains options.
Show child attributes
engine_versions array Compatible engine versions for this conversion type. Available, if the include argument contains engine_versions.
Show child attributes
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"