Show a batch

The batch with all its conversions. ?wait=N waits until all of them are done.

GEThttps://api.switchfile.io/v1/batches/{id}

Needs an API key: Authorization: Bearer YOUR_API_KEY. See Authentication.

Example

Request

curl "https://api.switchfile.io/v1/batches/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90?wait=30" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v1/batches/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90?wait=30", {
  headers: {
    Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

<?php
$ch = curl_init('https://api.switchfile.io/v1/batches/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90?wait=30');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $response");
}
print_r(json_decode($response, true));

import os
import requests

res = requests.get(
    "https://api.switchfile.io/v1/batches/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90?wait=30",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

Parameters

Path parameters

idstring (uuid)required
ID of the batch

Query parameters

waitnumber
Wait up to this many seconds until it is done (at most 30)
0 to 300 · example: 30

Headers

X-End-Userstring
Service keys only: an ID for the visitor you act for (1 to 128 characters: letters, digits and . _ : @ -). Quotas and rate limits then count per visitor.
X-End-User-Ipstring
Required with X-End-User: the IP address of the visitor.

Responses

200OK
archiveBatchArchiverequired
archive.expires_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
archive.formatstringrequired
one of "zip"
archive.statusstringrequired
one of "pending", "ready", "empty"
archive.urlstring | nullrequired
Signed URL of the ZIP file, set when status is ready
conversionsConversion[]required
conversions[].batch_idstring (uuid) | nullrequired
conversions[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
conversions[].creditsstring (integer) | integerrequired
Credits used, set once the conversion is done
conversions[].download_urlstring | nullrequired
Signed URL of the first result file
conversions[].errorobject | nullrequired
conversions[].error.codestringrequired
conversions[].error.messagestringrequired
conversions[].expires_atstring | nullrequired
Input and result are deleted at this time
conversions[].finished_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
conversions[].idstring (uuid)required
conversions[].inputobjectrequired
conversions[].input.filenamestring | nullrequired
conversions[].input.formatstring | nullrequired
conversions[].input.sizestring (integer) | integerrequired
conversions[].linksobjectrequired
conversions[].links.selfstringrequired
conversions[].objectstringrequired
one of "conversion"
conversions[].optionsmap of anyrequired
keys match ^(.*)$
conversions[].progressstring (integer) | integerrequired
Progress in percent
0 to 100
conversions[].resultobject | nullrequired
conversions[].result.filesConversionFile[]required
conversions[].result.files[].filenamestringrequired
conversions[].result.files[].sizestring (integer) | integerrequired
conversions[].result.files[].urlstringrequired
Signed download URL, works without an API key until expires_at
conversions[].statusstringrequired
one of "queued", "processing", "finished", "failed"
conversions[].tostringrequired
countsobjectrequired
counts.failedstring (integer) | integerrequired
counts.finishedstring (integer) | integerrequired
counts.totalstring (integer) | integerrequired
created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
idstring (uuid)required
linksobjectrequired
links.selfstringrequired
objectstringrequired
one of "batch"
statusstringrequired
one of "processing", "finished"
200 application/json
```
{
  "id": "5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90",
  "object": "batch",
  "status": "finished",
  "counts": {
    "total": 1,
    "finished": 1,
    "failed": 0
  },
  "conversions": [
    {
      "id": "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
      "object": "conversion",
      "status": "finished",
      "progress": 100,
      "input": {
        "filename": "a.heic",
        "format": "heic",
        "size": 1843200
      },
      "to": "jpg",
      "options": {},
      "result": {
        "files": [
          {
            "filename": "a.jpg",
            "size": 402113,
            "url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/a.jpg?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8"
          }
        ]
      },
      "download_url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/a.jpg?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
      "error": null,
      "credits": 1,
      "batch_id": "5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90",
      "created_at": "2026-11-06T18:00:00+00:00",
      "finished_at": "2026-11-06T18:00:02+00:00",
      "expires_at": "2026-11-07T18:00:02+00:00",
      "links": {
        "self": "https://api.switchfile.io/v1/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10"
      }
    }
  ],
  "archive": {
    "format": "zip",
    "status": "ready",
    "url": "https://api.switchfile.io/v1/archives/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
    "expires_at": "2026-11-07T18:00:02+00:00"
  },
  "created_at": "2026-11-06T18:00:00+00:00",
  "links": {
    "self": "https://api.switchfile.io/v1/batches/5c0f1d7a-6a54-4a49-b3c5-0c7d6a1e2f90"
  }
}
```

401The API key is missing or not validUNAUTHENTICATED

401 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "code": "UNAUTHENTICATED",
  "detail": "Missing or invalid API key."
}

403Not allowed: a signed URL is wrong or expired, or X-End-User was sent without a service keyEND_USER_NOT_ALLOWED

403 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-end-user-not-allowed",
  "title": "End user not allowed",
  "status": 403,
  "code": "END_USER_NOT_ALLOWED",
  "detail": "The X-End-User header is only allowed with a service key."
}

404Does not exist for this accountNOT_FOUND

404 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-not-found",
  "title": "Not found",
  "status": 404,
  "code": "NOT_FOUND",
  "detail": "Batch not found."
}

422Invalid data. errors names the fieldsINVALID_DATA

422 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-invalid-data",
  "title": "Invalid data",
  "status": 422,
  "code": "INVALID_DATA",
  "detail": "The request contains invalid data.",
  "errors": {
    "to": [
      "Expected string"
    ]
  }
}

429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED

429 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "Too many requests. Try again in 12 seconds."
}

Error bodies and codes are explained in Errors.