Jobs

Create jobs

Create a job with one ore more tasks. Requires the task.write scope.

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

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.

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

Show a job

Show a job. Requires the task.read scope.

Returns

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

Wait until the job status is finished or error. This makes the request block until the job has been completed. Requires the task.read scope.

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.

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.

Endpoint

GET https://api.cloudconvert.com/v2/jobs/{ID}/wait

Example Request

$ curl -g "https://api.cloudconvert.com/v2/jobs/c85f3ca9-164c-4e89-8ae2-c08192a7cb08/wait" \
       -H "Authorization: Bearer API_KEY"

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"