# Understanding the score

Every completed case carries a **`score`** — a single integer from **0 to 100** that
rates the accessibility quality of the **remediated** PDF/UA result. You read it from
[`GET /job-status/{caseId}`](https://docs.accessful.de/reference/job-status/):

```json
{ "jobStatus": "completed", "stage": "finished", "score": 87 }
```

Higher is better: **100** means no accessibility problems remained after remediation.

## When the score is final

The number is only meaningful once the job is **`completed`** (`stage: finished`).
Before that it is a placeholder — a `queued` case reports `"score": 0`, and during
[`revalidating`](https://docs.accessful.de/reference/job-status/#processing-stage) the score is still being
recomputed against the remediated file. Read it only after the terminal
[`completed`](https://docs.accessful.de/reference/job-status/) status; ignore it for every other state.

**Note:** The score describes the **result we produce**, not your upload. It measures what is
still wrong *after* Accessful has fixed everything it could — so it answers "how
accessible is the file I'm about to download", not "how bad was the original".

## How it's calculated

The score is **penalty-based**. Every file starts at **100**, and each accessibility
problem that **remains** in the result subtracts from it. Four things shape the number:

- **Severity dominates.** A structural blocker costs far more than a cosmetic finding.
  Severities, heaviest first:

  | Severity | What it covers |
  | --- | --- |
  | Blocker | Core tag structure, untagged images, missing document language |
  | Major | Significant structural problems for assistive technology |
  | Minor | Metadata, bookmarks, page numbering, artifacts |
  | Info | Best-practice / informational findings |

- **Fixed costs nothing.** Only **open** findings count. Everything Accessful
  successfully remediated is free — that is the whole point of the conversion.
- **Repeats don't dominate.** Many findings of the *same* type are dampened
  logarithmically, so the same issue across 200 pages is not penalised 200× more than
  it would be on one page.
- **Manual review is cheap.** A few issues can't be auto-fixed with confidence (e.g.
  "is this alt text actually meaningful?"). Those carry a small flat penalty instead of
  the full severity weight and are left for a human to confirm.

**A quality signal, not a legal certificate:** A high score means few accessibility problems remain — it is **not** a guarantee of
legal PDF/UA conformance and not a substitute for a manual accessibility audit. Treat
it as a strong indicator, not a compliance sign-off.

The exact weighting is tuned over time as remediation quality improves; only the
**0–100 range** and "higher is better" are part of the API contract.

## Reading a score

The API returns only the number. As a practical rule of thumb:

| Score | Read it as | Typical action |
| --- | --- | --- |
| **90–100** | Excellent — essentially clean | Ship it. |
| **75–89** | Good — minor issues remain | Usable as-is; spot-check high-stakes documents. |
| **50–74** | Fair — real gaps remain | Review before publishing; the source likely had structural weaknesses. |
| **Below 50** | Poor | The source was hard to remediate automatically; improve it and re-upload. |

## Why a score isn't higher

The most common reason a score plateaus below 100 is the **source document**: a scanned
PDF with no text layer, images that can't be described with confidence, or content
whose reading order can't be inferred safely. Accessful fixes structure, tags,
metadata, language and alt text wherever it can determine them reliably, and leaves the
rest as open or manual-review findings rather than guessing.

To move the number, **improve the source** — add a real text layer, supply genuine
headings — and upload the new file. Re-submitting the *same* bytes won't help: identical
content is detected as a [duplicate](https://docs.accessful.de/reference/upload/) and skipped.