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
).
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 |
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"