---
title: "Evidence and spans"
summary: "How to send evidence, how to name it, how span ids like ev_1:0 point back at your sentences, and the limits on a request."
category: "developer"
tags: ["evidence", "spans", "span ids", "ids", "limits", "source"]
updated: "2026-09-14T04:25:01.844Z"
url: "https://support.quorumtech.ch/articles/api-evidence-and-spans"
markdown: "https://support.quorumtech.ch/articles/api-evidence-and-spans.md"
---

# Evidence and spans

Evidence is what a verdict is judged against. Every span id in a response points back at a sentence of the evidence you sent, so you can show a reader exactly which line supported or contradicted a claim.

## An evidence item

```json
{
  "id": "annual-report-2025",
  "content": "Group revenue for FY2025 was CHF 94.0m, up from CHF 82.0m in the prior year. Operating margin improved to 18%.",
  "source": {
    "title": "FY2025 Annual Report",
    "uri": "https://example.com/reports/fy2025.pdf",
    "author": "Group Finance",
    "publishedAt": "2026-03-14",
    "retrievedAt": "2026-09-01"
  }
}
```

- `content` is the text, split into sentences on the server. It is the only field the verdict depends on.
- `id` is your name for the item: letters, digits, dot, dash and underscore, at most 64 characters, unique within the request. It **may not contain a colon**, because span ids use one. Without an id, items are numbered `ev_1`, `ev_2` in order.
- `source` is shown in explanations and never used to retrieve anything. Dates go in any recognisable form.

## Span ids

A span id is `<evidence id>:<ordinal>`, where the ordinal counts sentences within that item from zero. `annual-report-2025:1` is the second sentence of the item above.

Two guarantees:

- **Every span id in a response resolves to text you sent.** Ids a model invents are removed before the response is built, and the removal shows in `audit.referentialIntegrity`.
- **A span appears in a list only when the underlying statement holds.** An evaluator reads sentences whether or not they turn out to matter. A sentence it looked at while concluding "nothing here refutes the claim" is not contradicting evidence and does not appear in `contradictingSpans`.

An empty list can mean "not checked". Compare `explanation.axesRun` against `explanation.axesExpected`: if the contradiction axis did not run, `contradictingSpans` is empty because nothing looked. `degraded` says so too.

## Loaded batches use document spans

When you check against a batch, spans are `<document id>:<span index>` where the document id is the one you gave (or the filename, made safe) and the index counts citable spans in the parsed document. A batch-mode result also returns the span text in `cited`, so you do not need the document to show the citation.

## Limits on one request

| What | Limit |
| --- | --- |
| Claim | 1 to 4,000 characters |
| Evidence items | 1 to 50 |
| Evidence text, all items together | 200,000 characters |
| Request body | 8 MB |
| Claims in one bulk call | 100 |

Over a limit the API answers 400 `invalid_request` with `error.issues` naming the field.

## Writing good evidence

- Send the passages the claim was written from, not the whole corpus. A batch is the tool for a corpus.
- Keep an item to one source. Mixing two documents in one `content` makes precedence impossible to judge.
- Give dates in `source.publishedAt` when sources may conflict: Attest lets a later, primary source supersede an earlier one only when it can see which is which.
- Keep the ids stable across calls so citations in your own records stay meaningful.