> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Jobs

> Queue conversion and compression jobs for larger batches.

Use jobs when a batch should be processed by the worker queue instead of blocking the request. The jobs API uploads source files, creates a queued job record, and lets Convertly workers handle conversion or compression outside the request lifecycle.

<div className="convertly-callout">
  Jobs are storage-backed because workers need persisted source files. For storage-free processing, use synchronous `POST /api/convert` or `POST /api/compress`.
</div>

## What jobs achieve

| Goal                     | How jobs help                                                             |
| ------------------------ | ------------------------------------------------------------------------- |
| Keep your app responsive | Your request returns once files are uploaded and the job is queued.       |
| Process many files       | Workers can handle larger batches within the limits of the user's plan.   |
| Track progress           | Poll job status to show pending, processing, completed, or failed states. |
| Build workflows          | Combine jobs with webhooks to continue work after conversion completes.   |

## Create a job

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "jobType=convert" \
  -F "saveToStorage=true" \
  -F "files=@./input.png" \
  -F 'formats=["webp"]' \
  -F 'compressions=[82]' \
  -F 'resizes=["original"]' \
  -F "createArchive=false"
```

The response:

```json theme={"system"}
{
  "jobId": "a755a89a-3a63-4f3e-88ff-7fef50d42d7d",
  "status": "pending"
}
```

## Poll status

```bash theme={"system"}
curl "https://convertly.sh/api/jobs/a755a89a-3a63-4f3e-88ff-7fef50d42d7d" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
```

Job statuses include `pending`, `processing`, `completed`, and `failed`.

## Job lifecycle

<Steps>
  <Step title="Pending" icon="clock">
    The API accepted the files, stored them, and queued the worker task.
  </Step>

  <Step title="Processing" icon="spinner">
    A worker picked up the job and is updating progress.
  </Step>

  <Step title="Completed or failed" icon="circle-check">
    Results or `errorMessage` are available from `GET /api/jobs/{id}`.
  </Step>
</Steps>

## Cancel a queued job

```bash theme={"system"}
curl -X DELETE "https://convertly.sh/api/jobs/a755a89a-3a63-4f3e-88ff-7fef50d42d7d" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
```

Processing, completed, and failed jobs cannot be cancelled.