Skip to main content
Context attribution identifies which sources influenced each statement in an agent’s response and scores how strongly each one contributed. Run it from the SDK or REST API with the explainability methods. For how it works and the full list of source types, see Context attribution.

​
Attribute a response from an agent run

Use this method to attribute a response from a completed SeekrFlow agent thread. The SDK extracts the context, query, and response from the thread automatically. Endpoint: POST /v1/explainability/context-attributor-from-run 
import os
from seekrai import SeekrFlow

client = SeekrFlow(api_key=os.environ["SEEKR_API_KEY"])

attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
)
print(attribution)
To target a specific run rather than the latest, and to tune the analysis: 
attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
    run_id="<your-run-id>",
    granularity="sentence",
    top_k=5,
)

​
Attribute raw context

Use this method when you have the context, query, and response as text strings, for example when running attribution outside of SeekrFlow agents or in a custom pipeline. Endpoint: POST /v1/explainability/context-attributor 
attribution = client.explainability.get_context_attribution(
    context="France is a country in Western Europe with Paris as its capital. "
            "The Eiffel Tower is a wrought-iron lattice tower in Paris...",
    query="What is the capital of France and what is it known for?",
    response="Paris is the capital of France. It is known for the Eiffel Tower.",
    granularity="sentence",
    top_k=5,
)
print(attribution)

​
Attribute a specific portion of a response

Set highlight to focus attribution on one sentence or phrase instead of the whole response. When highlight is set, segments is empty and sources are returned in the top-level sources field: 
attribution = client.explainability.get_context_attribution_from_run(
    thread_id="<your-thread-id>",
    highlight="It is known for the Eiffel Tower.",
)

for source in attribution.sources:
    print(source.attribution, source.text)

​
Reading the result

Both methods return the same structure: the attributed response_text, a list of segments (one per sentence or chunk of the response), and the sources scored against each segment. Each source carries its source_type, the matched text, an attribution score, and its offset in the context. Tool-response sources add tool metadata (tool_name, tool_call_id, and a tool object whose fields vary by tool). For example, an mcp_tool object identifies an MCP tool call, including a sub-agent invoked as a tool, through its tool_name. For the source types you can encounter, see Source types. A result looks like this, with each segment carrying the sources that influenced it. Here one statement is attributed to an MCP tool response and another to the agent’s instructions: 
{
  "response_text": "Ticket OPS-482 is in progress. Always confirm status with the owner before closing.",
  "segments": [
    {
      "segment_index": 0,
      "segment_text": "Ticket OPS-482 is in progress.",
      "char_offset": 0,
      "sources": [
        {
          "source_type": "tool_response",
          "id": 0,
          "text": "{\"ticket_id\": \"OPS-482\", \"status\": \"In Progress\", \"owner\": \"Dana Ruiz\"}",
          "attribution": 0.89,
          "offset": 0,
          "tool_name": "get_ticket",
          "tool_call_id": "call_a1b2c3",
          "tool": {
            "type": "mcp_tool",
            "tool_name": "get_ticket",
            "tool_input": { "ticket_id": "OPS-482" }
          }
        }
      ]
    },
    {
      "segment_index": 1,
      "segment_text": "Always confirm status with the owner before closing.",
      "char_offset": 31,
      "sources": [
        {
          "source_type": "system_prompt",
          "id": 1,
          "text": "Always confirm ticket status with the owner before marking anything closed.",
          "attribution": 0.76,
          "offset": 142
        }
      ]
    }
  ],
  "highlight": null
}

​
Attribution scores

Each source has an attribution value between -1 and 1. Positive values indicate the source supported the response, meaning removing it would have caused the output to change. Values near 0 indicate little influence. Negative values are uncommon and indicate the source may have had a conflicting effect on the output.

​
Best practices

  • Granularity: Sentence-level gives the most interpretable results. When context is large and speed matters more than precision, use "chunk" with get_context_attribution_from_run or "paragraph" with get_context_attribution.
  • top_k: Values of 3–5 work well for most use cases. Increase toward 10 when debugging multi-hop answers where many sources contribute.
  • num_ablations: Leave unset in production. Override only when benchmarking or reproducing a specific result.
  • Segments with no strong sources: This indicates the model generated that content from prior knowledge rather than retrieved context. It is expected behavior, not an error.

​
Common errors

For the full list of status codes, see the API reference. The errors you are most likely to act on:
  • 404 Not found – The thread or run ID does not exist. Check the IDs you provided.
  • 422 Unprocessable entity – The thread has no assistant response, because generation is still in progress or the agent run failed.
  • 503 Service unavailable – The request timed out. Retry, reduce context size, or use a coarser granularity.
Last modified on July 8, 2026