Create a raw heatmap

curl https://api.tokenpath.ai/v1/attributions/heatmap \
  -H "Authorization: Bearer $TOKENPATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
    "question": "What drove Q4 revenue growth?",
    "answer": "Revenue improved because enterprise demand increased."
  }'

import os
import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions/heatmap",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    json={
        "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
        "question": "What drove Q4 revenue growth?",
        "answer": "Revenue improved because enterprise demand increased.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
heatmap = response.json()

for row, col, score in zip(heatmap["row"], heatmap["col"], heatmap["data"]):
    print(heatmap["answer_offsets"][row], "->", heatmap["document_offsets"][col], round(score, 3))

{
  "row": [0, 0, 0, "...", 1, 1, "..."],
  "col": [0, 1, 2, "...", 0, 1, "..."],
  "data": [0.8286, 0.0179, 0.0021, "...", 0.0176, 0.7631, "..."],
  "shape": [7, 14],
  "answer_offsets": [[0, 7], [7, 16], [16, 24], [24, 35], [35, 42], [42, 52], [52, 53]],
  "document_offsets": [[0, 7], [7, 16], [16, 19], [19, 21], [21, 22], "..."],
  "usage": { "prompt_tokens": 64, "document_tokens": 14, "answer_tokens": 7 },
  "offset_encoding": "utf-16"
}

POST https://api.tokenpath.ai/v1/attributions/heatmap

Returns the raw attention behind attribution: for every answer token, how much of its attention lands on each document token. Use it for research, debugging, and custom visualizations. For citations, use POST /v1/attributions. Requires the attributions:write scope. See Raw heatmap for how to read the result.

Request body

string

required

The source text. 1 to 400,000 characters. The heatmap comes from a single model context and is never windowed. A document that does not fit fails with 413 prompt_too_long.

string

required

The question or task the model was given. 1 to 10,000 characters.

string

required

The model’s answer. 1 to 10,000 characters.

string

default:"utf-16"

The unit for answer_offsets and document_offsets: utf-16, utf-32, or utf-8. See Offsets and encoding.

number

default:"0.001"

The smallest attention value to include. Range 0 to 1. Lower values return denser, larger responses.

Response

array of integer

Answer token index of each cell.

array of integer

Document token index of each cell. Parallel to row and data.

array of number

The share of answer token row[i]’s attention that lands on document token col[i], from 0 to 1.

[integer, integer]

[answer_tokens, document_tokens], the size of the full dense matrix.

array of [integer, integer]

[start, end] of every answer token in your answer, indexed by token.

array of [integer, integer]

[start, end] of every document token in your document, indexed by token.

object

prompt_tokens is the number of tokens the model processed, which is what you are billed for. document_tokens and answer_tokens are the parts of that count taken up by your document and answer.

string

The unit both offset arrays are counted in.

curl https://api.tokenpath.ai/v1/attributions/heatmap \
  -H "Authorization: Bearer $TOKENPATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
    "question": "What drove Q4 revenue growth?",
    "answer": "Revenue improved because enterprise demand increased."
  }'

import os
import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions/heatmap",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    json={
        "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
        "question": "What drove Q4 revenue growth?",
        "answer": "Revenue improved because enterprise demand increased.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
heatmap = response.json()

for row, col, score in zip(heatmap["row"], heatmap["col"], heatmap["data"]):
    print(heatmap["answer_offsets"][row], "->", heatmap["document_offsets"][col], round(score, 3))

{
  "row": [0, 0, 0, "...", 1, 1, "..."],
  "col": [0, 1, 2, "...", 0, 1, "..."],
  "data": [0.8286, 0.0179, 0.0021, "...", 0.0176, 0.7631, "..."],
  "shape": [7, 14],
  "answer_offsets": [[0, 7], [7, 16], [16, 24], [24, 35], [35, 42], [42, 52], [52, 53]],
  "document_offsets": [[0, 7], [7, 16], [16, 19], [19, 21], [21, 22], "..."],
  "usage": { "prompt_tokens": 64, "document_tokens": 14, "answer_tokens": 7 },
  "offset_encoding": "utf-16"
}

Tokens are the attribution model’s own subword tokens. A token’s range usually includes its leading space ([7, 16] is " improved"), and one word can span several tokens. Always slice with the returned offsets rather than splitting on whitespace.

Errors

In addition to the authentication errors:

Status	Code	Meaning
`402`	`insufficient_credits`	Your balance cannot cover the estimated cost. Nothing ran.
`413`	`prompt_too_long`	The request does not fit one model context. Shorten the document, or use `/v1/attributions`.
`422`	`validation_error`	A field is missing, empty, too long, or out of range.
`429`	`rate_limited`, `gpu_saturated`	Too many requests, or capacity is briefly full. Retry after `Retry-After`.
`5xx`	`gpu_backend_*`, `internal_error`	A server-side failure. Retry with backoff. Nothing is charged.

curl https://api.tokenpath.ai/v1/attributions/heatmap \
  -H "Authorization: Bearer $TOKENPATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
    "question": "What drove Q4 revenue growth?",
    "answer": "Revenue improved because enterprise demand increased."
  }'

import os
import httpx

response = httpx.post(
    "https://api.tokenpath.ai/v1/attributions/heatmap",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    json={
        "document": "Revenue improved in Q4 after stronger enterprise demand drove record subscription renewals.",
        "question": "What drove Q4 revenue growth?",
        "answer": "Revenue improved because enterprise demand increased.",
        "offset_encoding": "utf-32",
    },
    timeout=90.0,
)
response.raise_for_status()
heatmap = response.json()

for row, col, score in zip(heatmap["row"], heatmap["col"], heatmap["data"]):
    print(heatmap["answer_offsets"][row], "->", heatmap["document_offsets"][col], round(score, 3))

{
  "row": [0, 0, 0, "...", 1, 1, "..."],
  "col": [0, 1, 2, "...", 0, 1, "..."],
  "data": [0.8286, 0.0179, 0.0021, "...", 0.0176, 0.7631, "..."],
  "shape": [7, 14],
  "answer_offsets": [[0, 7], [7, 16], [16, 24], [24, 35], [35, 42], [42, 52], [52, 53]],
  "document_offsets": [[0, 7], [7, 16], [16, 19], [19, 21], [21, 22], "..."],
  "usage": { "prompt_tokens": 64, "document_tokens": 14, "answer_tokens": 7 },
  "offset_encoding": "utf-16"
}

Overview

Endpoints

Create a raw heatmap

Request body

Response

Errors

​Request body

​Response

​Errors

Request body

Response

Errors