Show a conversion

Status, progress, result, credits and expires_at. ?wait=N waits up to N seconds (at most 30) until the conversion is done.

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

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

Example

Request

curl "https://api.switchfile.io/v1/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10?wait=30" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v1/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10?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/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10?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/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10?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 conversion

Query parameters

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

Headers

Acceptstring
application/octet-stream together with wait: a finished conversion returns the file itself instead of JSON.
example: application/octet-stream
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
batch_idstring (uuid) | nullrequired
created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
creditsstring (integer) | integerrequired
Credits used, set once the conversion is done
download_urlstring | nullrequired
Signed URL of the first result file
errorobject | nullrequired
error.codestringrequired
error.messagestringrequired
expires_atstring | nullrequired
Input and result are deleted at this time
finished_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
idstring (uuid)required
inputobjectrequired
input.filenamestring | nullrequired
input.formatstring | nullrequired
input.sizestring (integer) | integerrequired
linksobjectrequired
links.selfstringrequired
objectstringrequired
one of "conversion"
optionsmap of anyrequired
keys match ^(.*)$
progressstring (integer) | integerrequired
Progress in percent
0 to 100
resultobject | nullrequired
result.filesConversionFile[]required
result.files[].filenamestringrequired
result.files[].sizestring (integer) | integerrequired
result.files[].urlstringrequired
Signed download URL, works without an API key until expires_at
statusstringrequired
one of "queued", "processing", "finished", "failed"
tostringrequired
200 application/json
```
{
  "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"
  }
}
```
303With Accept: application/octet-stream, done, larger than 50 MB. Location holds the download URL

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."
}

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": {
    "id": [
      "Expected string to match 'uuid' format"
    ]
  }
}

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.