Raw heatmap

POST /v1/attributions/heatmap returns the raw material behind every attribution: how much attention each answer token pays to each document token. Use it for research, debugging, and custom visualizations. For citations and highlights, use POST /v1/attributions, which does the aggregation for you.

Shape

The matrix is sparse and uses coordinate (COO) format. Three parallel arrays list only the cells above threshold:

{
  "row": [0, 0, 1, 1],
  "col": [0, 1, 1, 2],
  "data": [0.8286, 0.0179, 0.7631, 0.1719],
  "shape": [7, 14],
  "answer_offsets": [[0, 7], [7, 16], [16, 24], "..."],
  "document_offsets": [[0, 7], [7, 16], [16, 19], "..."],
  "offset_encoding": "utf-16"
}

Field	Meaning
`row[i]`	Answer token index.
`col[i]`	Document token index.
`data[i]`	The share of answer token `row[i]`’s attention that lands on document token `col[i]`, from 0 to 1.
`shape`	`[answer_tokens, document_tokens]`, the size of the full dense matrix.
`answer_offsets[t]`	`[start, end]` of answer token `t` in your `answer`.
`document_offsets[t]`	`[start, end]` of document token `t` in your `document`.
`offset_encoding`	The unit both offset arrays are counted in. See Offsets and encoding.

This excerpt is from the answer Revenue improved because enterprise demand increased. Answer token 1 ( improved) puts 76% of its attention on document token 1 (also improved). Token ranges usually include the leading space. row, col, and data always have the same length. shape and both offset arrays always describe every token, even when threshold filters out most cells. Each answer token’s attention adds up to 1 across everything the model reads, including the question and prompt. So the values in one row add up to at most 1.

Map cells back to text

cells = []
for row, col, score in zip(heatmap["row"], heatmap["col"], heatmap["data"]):
    a_start, a_end = heatmap["answer_offsets"][row]
    d_start, d_end = heatmap["document_offsets"][col]
    cells.append({
        "answer_text": answer[a_start:a_end],
        "source_text": document[d_start:d_end],
        "score": score,
    })

cells.sort(key=lambda cell: cell["score"], reverse=True)

Request "offset_encoding": "utf-32" when you slice in Python.

Threshold

threshold sets the smallest data value included. The default is 0.001.

Threshold	Effect
`0.0`	Every cell. Largest payload.
`0.001`	Default. Drops near-zero noise.
`0.1`	Strong links only. Handy when you want the top sources.

Limits

The heatmap comes from a single model context and is never windowed. document is capped at 400,000 characters, and a document that still does not fit the model’s context fails with 413 prompt_too_long. See Long documents. Copyable code for dense matrices and plots is in the raw heatmap cookbook.

Get started

Core concepts

Advanced

Use cases

Cookbooks

Resources

Shape

Map cells back to text

Threshold

Limits

​Shape

​Map cells back to text

​Threshold

​Limits

Shape

Map cells back to text

Threshold

Limits