List conversions

?ids=a,b,c (up to 50) returns several conversions with one request, in the order of ids. IDs that do not exist for your account are left out instead of failing with 404. Or send ?idempotency_key=K to look up the conversion that POST /v1/convert created with this Idempotency-Key, without creating anything. data is empty if none was created. While the first request is still running, the answer is 409 IDEMPOTENCY_KEY_IN_USE with Retry-After.

GEThttps://api.switchfile.io/v1/conversions

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

Example

Request

curl "https://api.switchfile.io/v1/conversions?ids=0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10,3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v1/conversions?ids=0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10,3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35", {
  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/conversions?ids=0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10,3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35');
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/conversions?ids=0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10,3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

Parameters

Query parameters

idsstring
Comma-separated conversion IDs, at most 50
1 to 4096 characters · example: 0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10,3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35
idempotency_keystring
Instead of ids: the Idempotency-Key of a POST /v1/convert. Returns the conversion it created, if any
1 to 255 characters

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

dataConversion[]required
Your conversions in the order of ids. IDs that do not exist for your account are left out
data[].batch_idstring (uuid) | nullrequired
data[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].creditsstring (integer) | integerrequired
Credits used, set once the conversion is done
data[].download_urlstring | nullrequired
Signed URL of the first result file
data[].errorobject | nullrequired
data[].error.codestringrequired
data[].error.messagestringrequired
data[].expires_atstring | nullrequired
Input and result are deleted at this time
data[].finished_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].idstring (uuid)required
data[].inputobjectrequired
data[].input.filenamestring | nullrequired
data[].input.formatstring | nullrequired
data[].input.sizestring (integer) | integerrequired
data[].linksobjectrequired
data[].links.selfstringrequired
data[].objectstringrequired
one of "conversion"
data[].optionsmap of anyrequired
keys match ^(.*)$
data[].progressstring (integer) | integerrequired
Progress in percent
0 to 100
data[].resultobject | nullrequired
data[].result.filesConversionFile[]required
data[].result.files[].filenamestringrequired
data[].result.files[].sizestring (integer) | integerrequired
data[].result.files[].urlstringrequired
Signed download URL, works without an API key until expires_at
data[].statusstringrequired
one of "queued", "processing", "finished", "failed"
data[].tostringrequired

200 application/json

{
  "data": [
    {
      "id": "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
      "object": "conversion",
      "status": "finished",
      "progress": 100,
      "input": {
        "filename": "report.docx",
        "format": "docx",
        "size": 48213
      },
      "to": "pdf",
      "options": {},
      "result": {
        "files": [
          {
            "filename": "report.pdf",
            "size": 61544,
            "url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.pdf?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8"
          }
        ]
      },
      "download_url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.pdf?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
      "error": null,
      "credits": 2,
      "batch_id": null,
      "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"
      }
    },
    {
      "id": "3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35",
      "object": "conversion",
      "status": "processing",
      "progress": 40,
      "input": {
        "filename": "talk.mov",
        "format": "mov",
        "size": 18874368
      },
      "to": "mp4",
      "options": {},
      "result": null,
      "download_url": null,
      "error": null,
      "credits": null,
      "batch_id": null,
      "created_at": "2026-11-06T18:00:00+00:00",
      "finished_at": null,
      "expires_at": null,
      "links": {
        "self": "https://api.switchfile.io/v1/conversions/3e2d9a4b-7c61-4f0e-8b52-1a9c0d7e6f35"
      }
    }
  ]
}

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": "Conversion not found."
}

409The request with this Idempotency-Key is still runningIDEMPOTENCY_KEY_IN_USE

409 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-idempotency-key-in-use",
  "title": "Idempotency key in use",
  "status": 409,
  "code": "IDEMPOTENCY_KEY_IN_USE",
  "detail": "A request with this Idempotency-Key is still running."
}

422More than 50 IDs, or an ID that is not a UUIDINVALID_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": {
    "ids": [
      "At most 50 IDs per request."
    ]
  }
}

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.