Jobs

Create 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: import-my-file, convert-my-file and export-my-file. You can name these tasks however you want, but only alphanumeric characters, - and _ are allowed in the task names.

Each task has a operation, which is the endpoint for creating the task (for example: convert, import/s3 or export/s3). The other parameters are the same as for creating the task using their direct endpoint. The input parameter allows it to directly reference the name of another task, created with the same job request.

Show all child parameters

operation string, required	The endpoint for creating the task (for example: `convert`, `import/s3` or `export/s3`)
input string or array, optional	The names of the input task for the task. Multiple task names can be provided as an array.
ignore_error boolean, optional	By default, the job fails if one task fails. You can ignore errors for specific tasks if you want to continue the job, even if one task fails.
... optional	Task specific options. Depends on `operation` and are the same as for creating the task using their direct endpoint.

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 job.finished or job.failed event. We do recommend using account wide webhooks which can be created via the dashboard.

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"
        }
      }
    ]
  }
}

Create jobs and wait for completion

Job Builder

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

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 job which results in longer processing times than usual. Using an asynchronous approach with webhooks is beneficial in such cases.

Arguments

tasks object, required

Show all child parameters

operation string, required	The endpoint for creating the task (for example: `convert`, `import/s3` or `export/s3`)
input string or array, optional	The names of the input task for the task. Multiple task names can be provided as an array.
ignore_error boolean, optional	By default, the job fails if one task fails. You can ignore errors for specific tasks if you want to continue the job, even if one task fails.
... optional	Task specific options. Depends on `operation` and are the same as for creating the task using their direct endpoint.

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

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

id string	The ID of the task.
name string	Your given name of the task.
operation string	Type of the task, for example `convert`, `import/s3` or `export/s3`.
status string	The status of the task. Is one of `waiting`, `queued`, `processing`, `finished` or `error`.
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.
engine string	Name of the engine.
engine_version string	Version of the engine.
result object	Result of the task. 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/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).

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.

This endpoint was previously available at https://api.cloudconvert.com/v2/jobs/{ID}/wait. Please migrate to the new base URL (https://sync.api.cloudconvert.com) for the synchronous API. We will shutdown the old endpoint on 28.02.2023. Affected customers are notified via email automatically.

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"

Convert Files

Optimize Files

Archives

Capture Websites

Merge Files

Convert Files

Capture Websites

Optimize Files

Other APIs

Automate

Documentation

Jobs

Create jobs

Returns

Endpoint

Example Request

Example Response

Create jobs and wait for completion

Returns

Endpoint

Example Request

Example Response

Show a job

Returns

Endpoint

Example Request

Example Response

Wait for a job

Returns

Endpoint

Example Request

Example Response

Lists jobs

Returns

Endpoint

Example Request

Example Response

Delete a job

Returns

Endpoint

Example Request