# 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.

`GET https://api.switchfile.io/v1/accessibility/checks`

Needs an API key: `Authorization: Bearer YOUR_API_KEY`. See [Authentication](https://switchfile.io/docs/authentication).

## Example

cURL:

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

Node.js:

```js
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:

```php
<?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));
```

Python:

```python
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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `idempotency_key` | string | yes | The Idempotency-Key sent with POST /v1/accessibility/checks (1 to 255 characters; example: 3f1c2a9e-check-1) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-End-User` | string | no | 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-Ip` | string | no | Required with X-End-User: the IP address of the visitor. |

## Responses

### 200: OK

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | AccessibilityCheck[] | yes | The check created with this key, or empty |
| `data[].created_at` | string | yes | ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00 |
| `data[].credits` | string (integer) \| integer | yes | Credits used, set once the check is done |
| `data[].error` | object \| null | yes |  |
| `data[].error.code` | string | yes |  |
| `data[].error.message` | string | yes |  |
| `data[].expires_at` | string \| null | yes | Input and report are deleted at this time |
| `data[].finished_at` | string \| null | yes | ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00 |
| `data[].id` | string (uuid) | yes |  |
| `data[].input` | object | yes |  |
| `data[].input.filename` | string \| null | yes |  |
| `data[].input.size` | string (integer) \| integer | yes |  |
| `data[].links` | object | yes |  |
| `data[].links.self` | string | yes |  |
| `data[].object` | string | yes | (one of "accessibility_check") |
| `data[].profile` | string | yes | (one of "auto", "ua1", "ua2") |
| `data[].report_pdf` | string \| null | yes | Also create the report as an accessible PDF in this language (one of "en") |
| `data[].result` | object \| null | yes |  |
| `data[].result.complete` | boolean | yes | false if the time limit was reached; the counts cover only the checked part |
| `data[].result.criteria` | object | yes |  |
| `data[].result.criteria.applied` | string (integer) \| integer | yes | Machine-checkable criteria that apply to this file (at least 0) |
| `data[].result.criteria.failed` | string (integer) \| integer | yes | (at least 0) |
| `data[].result.criteria.met` | string (integer) \| integer | yes | (at least 0) |
| `data[].result.manual_review_needed` | boolean | yes | Always true: software cannot check everything. A person who knows the content has to review it (one of true) |
| `data[].result.pages` | string (integer) \| integer | yes | (at least 0) |
| `data[].result.profile` | string | yes | (one of "ua1", "ua2") |
| `data[].result.report_json_url` | string | yes | Signed URL of the full report as JSON |
| `data[].result.report_pdf_url` | string \| null | yes | Signed URL of the report as PDF (with report_pdf) |
| `data[].result.summary` | string | yes | X of Y machine-checkable criteria met; manual review needed |
| `data[].result.topics` | AccessibilityTopic[] | yes | Topics with failed criteria, most failed checks first |
| `data[].result.topics[].explanation` | string | yes | What the problem means for people who use assistive technology |
| `data[].result.topics[].failed_checks` | string (integer) \| integer | yes | Number of failed checks in this topic (at least 0) |
| `data[].result.topics[].fix` | object | yes |  |
| `data[].result.topics[].id` | string | yes | Stable topic ID, for example alt-text |
| `data[].result.topics[].pages` | string (integer) \| integer[] | yes | Affected pages, at most 100 |
| `data[].result.topics[].title` | string | yes |  |
| `data[].status` | string | yes | (one of "queued", "processing", "finished", "failed") |

Example (application/json):

```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"
      }
    }
  ]
}
```

### 401: The API key is missing or not valid (`UNAUTHENTICATED`)

Example (application/problem+json):

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

### 403: Not allowed: a signed URL is wrong or expired, or X-End-User was sent without a service key (`END_USER_NOT_ALLOWED`)

Example (application/problem+json):

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

### 404: Does not exist for this account

### 409: The request with this Idempotency-Key is still running (`IDEMPOTENCY_KEY_IN_USE`)

Example (application/problem+json):

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

### 422: Invalid data. errors names the fields (`INVALID_DATA`)

Example (application/problem+json):

```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"
    ]
  }
}
```

### 429: Too many requests or a daily quota is used up. See Retry-After (`RATE_LIMIT_EXCEEDED`)

Example (application/problem+json):

```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](https://switchfile.io/docs/errors).