Find an accessibility check by Idempotency-Key

?idempotency_key=K looks up the check that POST /v1/accessibility/checks 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/accessibility/checks

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

Example

Request

curl "https://api.switchfile.io/v1/accessibility/checks?idempotency_key=3f1c2a9e-check-1" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v1/accessibility/checks?idempotency_key=3f1c2a9e-check-1", {
  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/accessibility/checks?idempotency_key=3f1c2a9e-check-1');
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/accessibility/checks?idempotency_key=3f1c2a9e-check-1",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

Parameters

Query parameters

idempotency_keystringrequired
The Idempotency-Key sent with POST /v1/accessibility/checks
1 to 255 characters · example: 3f1c2a9e-check-1

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

dataAccessibilityCheck[]required
The check created with this key, or empty
data[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].creditsstring (integer) | integerrequired
Credits used, set once the check is done
data[].errorobject | nullrequired
data[].error.codestringrequired
data[].error.messagestringrequired
data[].expires_atstring | nullrequired
Input and report 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.sizestring (integer) | integerrequired
data[].linksobjectrequired
data[].links.selfstringrequired
data[].objectstringrequired
one of "accessibility_check"
data[].profilestringrequired
one of "auto", "ua1", "ua2"
data[].report_pdfstring | nullrequired
Also create the report as an accessible PDF in this language
one of "en"
data[].resultobject | nullrequired
data[].result.completebooleanrequired
false if the time limit was reached; the counts cover only the checked part
data[].result.criteriaobjectrequired
data[].result.criteria.appliedstring (integer) | integerrequired
Machine-checkable criteria that apply to this file
at least 0
data[].result.criteria.failedstring (integer) | integerrequired
at least 0
data[].result.criteria.metstring (integer) | integerrequired
at least 0
data[].result.manual_review_neededbooleanrequired
Always true: software cannot check everything. A person who knows the content has to review it
one of true
data[].result.pagesstring (integer) | integerrequired
at least 0
data[].result.profilestringrequired
one of "ua1", "ua2"
data[].result.report_json_urlstringrequired
Signed URL of the full report as JSON
data[].result.report_pdf_urlstring | nullrequired
Signed URL of the report as PDF (with report_pdf)
data[].result.summarystringrequired
X of Y machine-checkable criteria met; manual review needed
data[].result.topicsAccessibilityTopic[]required
Topics with failed criteria, most failed checks first
data[].result.topics[].explanationstringrequired
What the problem means for people who use assistive technology
data[].result.topics[].failed_checksstring (integer) | integerrequired
Number of failed checks in this topic
at least 0
data[].result.topics[].fixobjectrequired
data[].result.topics[].idstringrequired
Stable topic ID, for example alt-text
data[].result.topics[].pagesstring (integer) | integer[]required
Affected pages, at most 100
data[].result.topics[].titlestringrequired
data[].statusstringrequired
one of "queued", "processing", "finished", "failed"

200 application/json

{
  "data": [
    {
      "id": "8c3e5a71-2f4b-4d6a-9e0c-7b1d3f5a2e48",
      "object": "accessibility_check",
      "status": "finished",
      "input": {
        "filename": "annual-report.pdf",
        "size": 482113
      },
      "profile": "auto",
      "report_pdf": "en",
      "result": {
        "summary": "38 of 41 machine-checkable criteria met; manual review needed",
        "profile": "ua1",
        "complete": true,
        "pages": 12,
        "criteria": {
          "applied": 41,
          "met": 38,
          "failed": 3
        },
        "manual_review_needed": true,
        "topics": [
          {
            "id": "alt-text",
            "title": "Figure or formula has no alternative text",
            "explanation": "A Figure or Formula tag has neither alternative text (/Alt) nor replacement text (/ActualText). Screen readers then announce only that there is a graphic, or skip it, so blind users miss information that exists only in the image, such as the message of a chart or the content of a formula.",
            "fix": {
              "word": [
                "Right-click the picture and choose View Alt Text (Office 2019 to 2024: Edit Alt Text)."
              ],
              "indesign": [
                "Select the image and choose Object > Object Export Options > Alt Text."
              ],
              "acrobat": [
                "Choose All tools > Prepare for accessibility > Add alternate text."
              ]
            },
            "failed_checks": 5,
            "pages": [
              1,
              2,
              7
            ]
          }
        ],
        "report_json_url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.json?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
        "report_pdf_url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.pdf?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8"
      },
      "error": null,
      "credits": 1,
      "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/accessibility/checks/8c3e5a71-2f4b-4d6a-9e0c-7b1d3f5a2e48"
      }
    }
  ]
}

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 account

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

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.