# Jobs

> Create, list, show, wait for and delete jobs.

## Create job <badge color="success" label="Async" size="lg"></badge>

Create a job with one ore more tasks.

<api-endpoint endpoint="jobs" method="POST">

[https://api.cloudconvert.com/v2/jobs](https://api.cloudconvert.com/v2/jobs)

</api-endpoint>

This endpoint is **asynchronous** and immediately responds after job creation with a job in status `processing`. There is also a [synchronous](#create-job-and-wait) version of this endpoint available.

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Body

<field-group>
<field name="tasks" type="object" :required="true">

The tasks of the job, which are typically an import task, a conversion task and an export task. The keys of the object are the names of the tasks. You can name these tasks however you want, but only alphanumeric characters, - and _ are allowed in the task names.

<collapsible className="mb-0" close-text="Hide child" open-text="Show child">
<field-group>
<field name="operation" type="string" :required="true">

Each task has a operation, which is the endpoint for creating the task (for example: `convert`, `import/s3` or `export/s3`).

</field>

<field name="input" type="array">

The names of the input task for the task. Multiple task names can be provided as an array.

</field>

<field name="ignore_error" type="boolean">

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.

</field>

<field name="...">

Task specific options. Depends on operation and the available options can be found in the documentation of the specific operation.

</field>
</field-group>
</collapsible>
</field>

<field name="tag" type="string">

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.

</field>

<field name="webhook_url" type="string">

A [webhook](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) 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](https://cloudconvert.com/dashboard/api/v2/webhooks).

</field>
</field-group>

<tip to="https://cloudconvert.com/job-builder">

You can use the **Job Builder** to generate and try out job payloads.

</tip>

#### Example Body

<code-collapse name="Body">

```json
{
  "tasks": {
    "import-my-file": {
      "operation": "import/s3"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "export-my-file": {
      "operation": "export/s3",
      "input": "convert-my-file"
    }
  },
  "tag": "myjob-123"
}
```

</code-collapse>

#### Response

The endpoint returns the created job in `processing` status. You can find details about the job model response in the documentation about the [show jobs endpoint](#show-job).

---

## Create job and wait <badge color="error" label="Sync" size="lg"></badge>

Create a job and block until the job is completed. This is the **synchronous** version of the [create job endpoint](#create-job).

<api-endpoint endpoint="jobs" method="POST" :sync="true">

[https://sync.api.cloudconvert.com/v2/jobs](https://sync.api.cloudconvert.com/v2/jobs)

</api-endpoint>

<warning>

We do not recommend using this for long running jobs (e.g. video encodings). Your network stack might automatically time out requests if there is not data transferred for a longer time. As a good practice, 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](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) is beneficial in such cases.

</warning>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Body

<field-group>
<field name="tasks" type="object" :required="true">

The tasks of the job, which are typically an import task, a conversion task and an export task. The keys of the object are the names of the tasks. You can name these tasks however you want, but only alphanumeric characters, - and _ are allowed in the task names.

<collapsible className="mb-0" close-text="Hide child" open-text="Show child">
<field-group>
<field name="operation" type="string" :required="true">

Each task has a operation, which is the endpoint for creating the task (for example: `convert`, `import/s3` or `export/s3`).

</field>

<field name="input" type="array">

The names of the input task for the task. Multiple task names can be provided as an array.

</field>

<field name="ignore_error" type="boolean">

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.

</field>

<field name="...">

Task specific options. Depends on operation and are the same as for creating the task using their direct endpoint.

</field>
</field-group>
</collapsible>
</field>

<field name="tag" type="string">

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.

</field>

<field name="redirect" type="boolean">

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.

</field>
</field-group>

<tip to="https://cloudconvert.com/job-builder">

You can use the **Job Builder** to generate and try out job payloads.

</tip>

#### Example Body

<code-collapse name="Body">

```json
{
  "tasks": {
    "import-my-file": {
      "operation": "import/url",
      "url": "https://..."
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  },
  "tag": "myjob-123",
  "redirect": true
}
```

</code-collapse>

#### Response

The endpoint returns the completed job in `finsihed` or `error` status. You can find details about the job model response in the documentation about the [show jobs endpoint](#show-job).

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

---

## Show job <badge color="success" label="Async" size="lg"></badge>

Show a job status.

<api-endpoint endpoint="jobs/{ID}" method="GET">

[https://api.cloudconvert.com/v2/jobs/{ID}](https://api.cloudconvert.com/v2/jobs/%7BID%7D)

</api-endpoint>

This endpoint is asynchronous and immediately responds the job status, even if the job has not completed yet. There is also a [synchronous version](#wait-for-job) of this endpoint available.

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Query Parameters

<field-group>
<field name="redirect" type="boolean">

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.

</field>
</field-group>

#### Response

The job status, including tasks:

<field-group>
<field name="id" type="string">

The ID of the job.

</field>

<field name="tag" type="string">

Your given tag of the job.

</field>

<field name="status" type="string">

The status of the job. Is one of `waiting`, `processing`, `finished` or `error`.

</field>

<field name="created_at" type="string">

ISO8601 timestamp of the creation of the job.

</field>

<field name="started_at" type="string">

ISO8601 timestamp when the job started processing.

</field>

<field name="ended_at" type="string">

ISO8601 timestamp when the job finished or failed.

</field>

<field name="tasks" type="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](https://cloudconvert.com/docs/raw/api-reference/tasks.md#show-task).

<collapsible className="mb-0" close-text="Hide child attributes" open-text="Show child attributes">
<field-group>
<field name="id" type="string">

The ID of the task.

</field>

<field name="name" type="string">

Your given name of the task.

</field>

<field name="operation" type="string">

Type of the task, for example `convert`, `import/s3` or `export/s3`.

</field>

<field name="status" type="string">

The status of the task. Is one of `waiting`, `processing`, `finished` or `error`.

</field>

<field name="created_at" type="string">

ISO8601 timestamp of the creation of the task.

</field>

<field name="started_at" type="string">

ISO8601 timestamp when the task started processing.

</field>

<field name="ended_at" type="string">

ISO8601 timestamp when the task finished or failed.

</field>

<field name="engine" type="string">

Name of the engine.

</field>

<field name="engine_version" type="string">

Version of the engine.

</field>

<field name="result" type="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 below).

</field>
</field-group>
</collapsible>
</field>

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

#### Example Response

<code-collapse name="Response">

```json
{
  "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"
    }
  }
}
```

</code-collapse>
</field-group>

---

## Wait for job <badge color="error" label="Sync" size="lg"></badge>

Wait until the job status is completed and return the job status. This is the **synchronous** version of the [show job endpoint](#show-job).

<api-endpoint endpoint="jobs/{ID}" method="GET" :sync="true">

[https://sync.api.cloudconvert.com/v2/jobs/{ID}](https://sync.api.cloudconvert.com/v2/jobs/%7BID%7D)

</api-endpoint>

<warning>

We do not recommend using this for long running jobs (e.g. video encodings). Your network stack might automatically time out requests if there is not data transferred for a longer time. As a good practice, 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](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) is beneficial in such cases.

</warning>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Query Parameters

<field-group>
<field name="redirect" type="boolean">

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.

</field>
</field-group>

#### Response

The finished or failed job, including tasks. You can find details about the job model response in the documentation about the [show job endpoint](#show-job).

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

```bash
HTTP/1.1 302 FOUND
Location: https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf
```

---

## List jobs

List all your jobs.

<api-endpoint endpoint="jobs" method="GET">

[https://api.cloudconvert.com/v2/jobs](https://api.cloudconvert.com/v2/jobs)

</api-endpoint>

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.read` scope.

</field>

#### Query Parameters

<field-group>
<field name="filter[status]" type="string">

The result will be filtered to include only jobs with a specific status (`processing`, `finished` or `error`).

</field>

<field name="filter[tag]" type="string">

The result will be filtered to include only jobs with a tag.

</field>

<field name="filter[access_token]" type="string">

The result will be filtered to include only jobs created with a specific access token (API key) ID.

</field>

<field name="include" type="array">

Include `tasks` in the result.

</field>

<field name="per_page" type="number">

Number of tasks per page, defaults to `100`, maximum `1000`.

</field>

<field name="page" type="number">

The result page to show.

</field>
</field-group>

#### Response

The list of jobs. You can find details about the job model response in the documentation about the [show jobs endpoint](#show-job).

#### Example Response

<code-collapse name="Response">

```json
{
  "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
  }
}
```

</code-collapse>

---

## Delete job

Delete a job, including all tasks and data. Requires the `task.write` scope.

<api-endpoint endpoint="jobs/{ID}" method="DELETE">

[https://api.cloudconvert.com/v2/jobs/{ID}](https://api.cloudconvert.com/v2/jobs/%7BID%7D)

</api-endpoint>

Jobs are deleted automatically 24 hours after they have ended.

#### Authentication

<field name="Authorization" type="header" :required="true">

The Authorization header expects a Bearer token with the `task.write` scope.

</field>

#### Response

An empty response with HTTP Code `204`.