Jobs
Create a job with one ore more tasks. Requires the task.write
scope.
This endpoint is asynchronous and immediately responds after job creation. There is also a synchronous version of this endpoint available.
Arguments | |
---|---|
tasks object, required |
The example on the right consists of three tasks:
Each task has a |
tag string, optional |
An arbitrary string to identify the job. Does not have any effect and can be used to associate the job with an ID in your application. |
webhook_url string, optional |
A webhook that is used for this single job only. The url will receive a |
Returns
The created job. You can find details about the job model response in the documentation about the show jobs endpoint.
Endpoint
POST https://api.cloudconvert.com/v2/jobs
Example Request
$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \ -H "Authorization: Bearer API_KEY" \ -H "Content-type: application/json" \ -d '
{ "tasks": { "import-my-file": { "operation": "import/s3" }, "convert-my-file": { "operation": "convert", "input": "import-my-file", "input_format": "docx", "output_format": "pdf", "page_range": "1-2", "optimize_print": true }, "export-my-file": { "operation": "export/s3", "input": "convert-my-file" } }, "tag": "myjob-123" }
'
Example Response
{
"data": {
"id": "6559c281-ed85-4728-80db-414561c631e9",
"tag": "myjob-123",
"status": "waiting",
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": null,
"ended_at": null,
"tasks": [
{
"id": "7f110c42-3245-41cf-8555-37087c729ed2",
"name": "import-my-file",
"operation": "import/s3",
"status": "processing",
"credits": null,
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": "2018-09-19T14:42:58+00:00",
"ended_at": null,
"result": null
},
{
"id": "7a142bd0-fa20-493e-abf5-99cc9b5fd7e9",
"name": "convert-my-file",
"operation": "convert",
"status": "waiting",
"credits": null,
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": null,
"ended_at": null,
"engine": "office",
"engine_version": "2016",
"result": null,
"depends_on_tasks": {
"import-my-file": "u0HON3MJDk"
}
},
{
"id": "36af6f54-1c01-45cc-bcc3-97dd23d2f93d",
"name": "export-my-file",
"operation": "export/s3",
"status": "waiting",
"credits": null,
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": null,
"ended_at": null,
"result": null,
"depends_on_tasks": {
"convert-my-file": "KPpekWbRRq"
}
}
]
}
}
Job creation is asynchronous by default. When creating a job, the API responds immediately and you either receive the completed job via webhook notification or via polling.
As alternative, there is a synchronous option which waits until the job status is
finished
or error
. This makes the
request block until the job has been completed.
Requires the task.write
scope. Please note that the synchronous API uses a
different
base URL (https://sync.api.cloudconvert.com
).
Arguments | |
---|---|
tasks object, required |
The example on the right consists of three tasks:
Each task has a |
tag string, optional |
An arbitrary string to identify the job. Does not have any effect and can be used to associate the job with an ID in your application. |
redirect boolean, optional |
When set to |
Returns
The finished or failed job, including tasks. You can find details about the job model response in the documentation about the show job endpoint.
If redirect
was set to true
, it redirects to the output file of the job (a 302
redirect with the Location
header pointing to the output file).
Endpoint
POST https://sync.api.cloudconvert.com/v2/jobs
Example Request
$ curl -X POST "https://sync.api.cloudconvert.com/v2/jobs" \ -H "Authorization: Bearer API_KEY" \ -H "Content-type: application/json" \ -d '
{ "tasks": { "import-my-file": { "operation": "import/s3" }, "convert-my-file": { "operation": "convert", "input": "import-my-file", "input_format": "docx", "output_format": "pdf", "page_range": "1-2", "optimize_print": true }, "export-my-file": { "operation": "export/s3", "input": "convert-my-file" } }, "tag": "myjob-123", "redirect": true }
'
Example Response
HTTP/1.1 302 FOUND
Location: https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf
Show a job
Show a job. Requires the task.read
scope.
This endpoint is asynchronous and immediately responds the job status, even if the job has not completed yet. There is also a synchronous version of this endpoint available.
Query Parameters | |
---|---|
redirect boolean, optional |
When set to true the response will a be a redirect to the export URL of the
job. Using this parameter requires that the job has an export/url task.
|
Returns
The job status, including tasks.
If redirect
was set to true
, it redirects to the output file of the
job (a 302
redirect with the Location
header pointing to the output file).
Attributes | |
---|---|
id string | The ID of the job. |
tag string | Your given tag of the job. |
status string |
The status of the job. Is one of waiting , processing , finished
or error
.
|
created_at string | ISO8601 timestamp of the creation of the job. |
started_at string | ISO8601 timestamp when the job started processing. |
ended_at string | ISO8601 timestamp when the job finished or failed. |
tasks array |
List of tasks that are part of the job. You can find details about the task model response
in the documentation about the show tasks
endpoint.
Show child attributes |
Endpoint
GET https://api.cloudconvert.com/v2/jobs/{ID}
Example Request
$ curl -g "https://api.cloudconvert.com/v2/jobs/9a160154-58e2-437f-9b6b-19d63b1f59e3" \
-H "Authorization: Bearer API_KEY"
Example Response
{
"data": {
"id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
"tag": "myjob-123",
"status": "processing",
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": "2018-09-19T14:42:58+00:00",
"tasks": [
{
"id": "1f34c1b5-9ee8-4c8c-890f-bf44cda1deb7",
"operation": "convert",
"status": "finished",
"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,
"result": {
"files": [
{
"filename": "output.pdf"
}
]
},
"links": {
"self": "https://api.cloudconvert.com/v2/tasks/h451E6HMhG"
}
},
{
"id": "48c6e72b-cb8e-4ecc-bf3d-ead5477b4741",
"operation": "export/url",
"status": "finished",
"credits": null,
"message": null,
"code": null,
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": null,
"ended_at": null,
"result": {
"files": [
{
"filename": "output.pdf",
"url": "https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf"
}
]
},
"links": {
"self": "https://api.cloudconvert.com/v2/tasks/Xhrek8bGGq"
}
}
],
"links": {
"self": "https://api.cloudconvert.com/v2/jobs/Xh56hvvMhG"
}
}
}
Wait for a job
The CloudConvert API is asynchronous by default. When starting a job, the API responds immediately and you either receive the completed job via webhook notification or via polling.
As alternative, there is a synchronous option which waits until the job status is
finished
or error
. This makes the
request block until the job has been completed.
Requires the task.read
scope. Please note that the synchronous API uses a different
base URL (https://sync.api.cloudconvert.com
).
Query Parameters | |
---|---|
redirect boolean, optional |
When set to true the response will a be a redirect to the export URL of the
job. Using this parameter requires that the job has an export/url task.
|
Returns
The finished or failed job, including tasks. You can find details about the job model response in the documentation about the show job endpoint.
If redirect
was set to true
, it redirects to the output file of the job (a 302
redirect with the Location
header pointing to the output file).
Endpoint
GET https://sync.api.cloudconvert.com/v2/jobs/{ID}
Example Request
$ curl -g "https://sync.api.cloudconvert.com/v2/jobs/c85f3ca9-164c-4e89-8ae2-c08192a7cb08?redirect=true" \
-H "Authorization: Bearer API_KEY"
Example Response
HTTP/1.1 302 FOUND
Location: https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf
Lists jobs
List all jobs. Requires the task.read
scope.
Query Parameters | |
---|---|
filter[status] string, optional |
The result will be filtered to include only jobs with a specific status (processing , finished or error ).
|
filter[tag] string, optional | The result will be filtered to include only jobs with a tag. |
include array, optional |
Include 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 jobs. You can find details about the job model response in the documentation about the show jobs endpoint.
Endpoint
GET https://api.cloudconvert.com/v2/jobs
Example Request
$ curl -g "https://api.cloudconvert.com/v2/jobs" \
-H "Authorization: Bearer API_KEY"
Example Response
{
"data": [
{
"id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
"tag": "myjob-123",
"status": "processing",
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": "2018-09-19T14:42:58+00:00",
"links": {
"self": "https://api.cloudconvert.com/v2/tasks/Xh56hvvMhG"
}
},
{
"id": "e8d19289-f8f0-4e83-928a-4705606b086b",
"status": "processing",
"created_at": "2018-09-19T14:42:58+00:00",
"started_at": "2018-09-19T14:42:58+00:00",
"links": {
"self": "https://api.cloudconvert.com/v2/tasks/2h56hvvMhG"
}
},
}
],
"links": {
"first": "https://api.cloudconvert.com/v2/jobs?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.cloudconvert.com/v2/jobs",
"per_page": 100,
"to": 2
}
}
Delete a job
Delete a job, including all tasks and data. Requires the task.write
scope.
Jobs are deleted automatically 24 hours after they have ended.
Returns
An empty response with HTTP Code 204.
Endpoint
DELETE https://api.cloudconvert.com/v2/jobs/{ID}
Example Request
$ curl -X DELETE "https://api.cloudconvert.com/v2/jobs/h451E6HMhG" \
-H "Authorization: Bearer API_KEY"