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

> How Convertly queues, processes, tracks, and completes larger media jobs.

Async jobs let your app upload files once, receive a `jobId`, and let Convertly workers process the batch in the background. Jobs are useful when a conversion or media tool may take longer than a user should wait on a single request.

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

## Why jobs exist

Synchronous APIs are convenient, but media processing can be slow when files are large, batches are wide, or outputs need heavier work. The jobs API moves that work into a queue so your app can stay responsive while Convertly handles processing.

## Job lifecycle

<Steps>
  <Step title="Upload and queue">
    Your app sends files and settings to `POST /api/jobs`, or sends `async=true` to a media tool endpoint. Convertly stores the source files and creates a pending job.
  </Step>

  <Step title="Worker processing">
    A worker picks up the job, processes each file, and updates progress as files complete or fail.
  </Step>

  <Step title="Result retrieval">
    Your app polls `GET /api/jobs/{id}` or reacts to webhooks to retrieve completed results.
  </Step>
</Steps>

## Job statuses

| Status       | Meaning                                                |
| ------------ | ------------------------------------------------------ |
| `pending`    | The job has been accepted and is waiting for a worker. |
| `processing` | A worker is actively processing files.                 |
| `completed`  | Processing finished and results are available.         |
| `failed`     | The job could not be completed. Check `errorMessage`.  |

## When to use jobs

Use jobs for bulk imports, agency/client file batches, large video or audio files, workflow builders, user dashboards with progress states, or anything that should survive a browser refresh.

## Async media tools

Media tool endpoints can be queued directly:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/media/extract-audio" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/interview.mp4" \
  -F "format=mp3" \
  -F "async=true"
```

The response contains the same job identifier used by conversion jobs:

```json theme={"system"}
{
  "jobId": "65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e",
  "status": "pending",
  "tool": "extract-audio"
}
```

Poll the job endpoint:

```bash theme={"system"}
curl "https://convertly.sh/api/jobs/65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
```

## Idempotency and callbacks

Send an `Idempotency-Key` header when creating jobs from retry-prone systems. If the same key is sent again for the same account, Convertly returns the existing job instead of creating duplicate work or charging another media operation.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Idempotency-Key: import-42-image-7" \
  -F "files=@./hero.jpg" \
  -F "saveToStorage=true" \
  -F "formats=[\"webp\"]"
```

For one-off integrations, pass `callbackUrl` and `callbackSecret` when creating the job. Convertly signs the callback as `HMAC_SHA256(timestamp.body)` and sends it in `Convertly-Signature`.