> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenpath.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Long documents

> Size limits, automatic windowing, timeouts, and billing for large source text.

`POST /v1/attributions` takes source text of up to 4,000,000 characters, or about a million tokens of ordinary prose, in a single call. You send the whole document and TokenPath handles the rest.

## Limits

| Input      | `/v1/attributions`                                      | `/v1/attributions/heatmap`                    |
| ---------- | ------------------------------------------------------- | --------------------------------------------- |
| `document` | 1 to 4,000,000 characters, and at most 1,050,000 tokens | 1 to 400,000 characters, in one model context |
| `question` | 1 to 10,000 characters                                  | 1 to 10,000 characters                        |
| `answer`   | 1 to 10,000 characters                                  | 1 to 10,000 characters                        |

Character limits are checked first and fail with `422 validation_error`. The token ceiling is counted with the attribution model's own tokenizer, over the document only, before any inference runs.

## How windowing works

A document that fits in the attribution model's context is attributed in one pass. A 20,000-token document, about 30 pages, typically returns in under two seconds.

A document that does not fit is split into overlapping, model-sized windows. TokenPath attributes the answer against each window in turn and keeps the strongest source for each answer phrase. Offsets always index into the full document you sent, never into a window.

Long requests are all or nothing. You get a result only after every window succeeds. If any window fails, or the whole request runs past its time budget, the request fails and returns no partial links.

<Tip>
  Set your HTTP client timeout to at least 300 seconds for documents longer than a few hundred thousand characters. Ordinary requests finish far sooner, and 90 seconds is plenty for them.
</Tip>

## Errors

| Status | Code                                 | What to do                                                                                                |
| ------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `413`  | `context_token_limit_exceeded`       | The document has more than 1,050,000 tokens. Shorten it.                                                  |
| `413`  | `too_many_context_chunks`            | The document needs more windows than one request allows. Shorten it, or split it into separate requests.  |
| `413`  | `prompt_too_long`                    | The question and answer are so long that they leave no room for any document text. Shorten them.          |
| `413`  | `long_context_attributions_disabled` | Windowing is temporarily switched off. Retry later, or send a document of 400,000 characters or fewer.    |
| `504`  | `long_context_timeout`               | The request ran past its time budget. Retry once with backoff. If it happens again, shorten the document. |

## Billing

TokenPath first holds credits based on the full request size. When the request succeeds, you pay for the tokens the model actually processed. For a windowed request, that is the sum across windows. The question, the answer, and the overlap between neighboring windows are processed once per window, so a windowed request costs a little more than the document's length alone suggests. See [Credits and billing](/concepts/credits-billing).

## The raw heatmap

`POST /v1/attributions/heatmap` does not window. Its token matrix comes from one model context, and matrices from separate windows cannot be merged without changing what the numbers mean. Keep heatmap documents to 400,000 characters or fewer, and use `/v1/attributions` for anything longer.