Trace a response to source documents

Source tracing lets you prove that any model or agent answer came directly from the exact files you uploaded. Every chunk retrieved from a vector database carries a traceable lineage that connects the model output to the retrieved chunk, its Markdown location, and the original uploaded file. This is designed to support auditability, compliance, and operational decision-making in environments where document-level proof of origin is required.

How source tracing works

When a file is ingested into a vector database, the pipeline captures provenance metadata for every chunk (line range, character offsets, heading hierarchy, and source page number) and stores it alongside the embedding. No additional configuration is required.

Retrieve source tracing fields from a run

After a run completes, list the thread’s messages to access the assistant response. When the agent invoked the file search tool, each retrieved chunk carries its source tracing fields: chunk_id (use it to fetch full provenance), page, lines, and section (the heading hierarchy path from the document root). page is null for native Markdown and JSON. Endpoint: GET /v1/threads/{thread_id}/messages

from seekrai import SeekrFlow

client = SeekrFlow()

messages = client.agents.threads.list_messages(thread_id="<thread-id>")

# The assistant response carries the retrieved chunks and their source tracing fields
assistant = next(m for m in messages if m.role == "assistant")
print(assistant.content)  # each file search chunk includes chunk_id, page, lines, and section

Retrieve chunk provenance

Use chunk_id with the chunk endpoint to retrieve the full provenance record, which includes the file_id of the original uploaded file, the chunk text as indexed, and a list of locations. Endpoint: GET /v1/flow/vectordb/{database_id}/chunk/{chunk_id} Retrieve a chunk with the seekrai SDK using retrieve_chunk. The returned object exposes the same fields as the REST response, so you can read file_id and walk each location directly. Requires seekrai 0.20.0 or later.

from seekrai import SeekrFlow

client = SeekrFlow()

chunk = client.vector_database.retrieve_chunk(
    database_id="<database-id>",
    chunk_id="<chunk-id>",  # from the file search result
)

print(chunk.file_id)   # original uploaded file
print(chunk.text)      # chunk text as indexed

for location in chunk.locations:
    print(location["page_number"], location["hierarchy"])

Use the file_id to download the original uploaded file and complete the chain of custody:

client.files.retrieve_content(chunk.file_id, output="source-document.pdf")

Reading the result

Each entry in a chunk’s locations pins the answer to a precise place in the ingested Markdown: the line range and character offsets, the heading hierarchy from the document root to the chunk, and the page_number in the source document (1-indexed, and null for native Markdown and JSON). Combined with file_id, these fields let you open the original document and point to the exact passage an answer was drawn from. For the complete record, see the chunk endpoint reference.

Supported file types

File type	`page_number`	`hierarchy`	`lines`	`char_start` / `char_end`
PDF	✓	✓	✓	✓
DOCX	✓	✓	✓	✓
PPTX	✓	✓	✓	✓
Markdown	—	✓	✓	✓
JSON	—	✓	✓	✓

Complete workflow

The full source tracing workflow follows this sequence:

Run the agent against a thread (Endpoint: POST /v1/threads/{thread_id}/runs), then wait for the run to complete.
List the thread’s messages (Endpoint: GET /v1/threads/{thread_id}/messages) to find the assistant response. Each retrieved chunk includes chunk_id, page, and section.
Call the chunk endpoint with chunk_id to get file_id and confirm the exact Markdown lines the answer was drawn from.
Use file_id with the file download endpoint (Endpoint: GET /v1/flow/files/{file_id}/content) to retrieve the original uploaded file and complete the chain of custody.

​How source tracing works

​Retrieve source tracing fields from a run

​Retrieve chunk provenance

​Reading the result

​Supported file types

​Complete workflow