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