# Batch downloads

Submit several explicit URLs as separately tracked jobs.

## Create a batch

`POST /batches` requires an API key or user session. It accepts from 1 to 10 items, or a lower operator-configured ceiling. Each item has the same shape as a [download request](/docs/en/reference/media#submit-a-download).

```json
{
    "items": [
        {
            "url": "https://example.com/one.mp4"
        },
        {
            "url": "https://example.com/two.jpg",
            "output": {
                "type": "image",
                "format": "original",
                "quality": "best"
            }
        }
    ]
}
```

A shortened `202` response:

```json
{
    "batch": {
        "id": "bat_example",
        "status": "queued",
        "totalItems": 2,
        "jobs": [
            "job_one",
            "job_two"
        ]
    }
}
```

Each child has its own status and file list. An Instagram album may produce multiple files from one child job.

## Follow a batch

`GET /batches/:id` requires the owning account and no body. Its `batch.jobs` field contains child objects with `id`, `status`, and `progress`. Creation returns ID strings; status lookup returns child objects. Do not assume both shapes are identical.

Poll individual jobs to read their complete results and errors. A batch's aggregate progress is not evidence that every child succeeded.

## Admission and retries

Admission is atomic: an invalid or over-capacity batch should not leave partially accepted children. The shared 10-pending-download account ceiling also applies. Wait for capacity before sending another batch.

Batch creation is not idempotent. Blindly resending a timed-out `/batches` request can create duplicate work. For per-item retry control, submit individual downloads with idempotency keys instead.

## Archives are a separate concern

The HTTP batch API does not return a ZIP, including when an `archiveName` is supplied. Your client/backend can assemble completed files, as the website does.

`POST /media/playlist` is an alias accepting the same item-list body. It is not the saved-playlist resource. The [standalone worker batch job](/docs/en/worker/jobs) is a different interface that creates an archive.

## Request examples

Choose a language. JavaScript and Node.js examples use a server environment, not a public browser key. Replace illustrative IDs with your own.

### Submit a batch

```request
{
    "method": "POST",
    "path": "/batches",
    "body": {
        "items": [
            {
                "url": "https://example.com/one.mp4"
            },
            {
                "url": "https://example.com/two.jpg"
            }
        ]
    }
}
```