Skip to main content

Run Traceability

When the LLM decides that answering your query requires using one or more agent tools, a run is created and associated with a unique run_id.

You can retrieve the full trace of that run (step-by-step) using the /chat/run/{run_id} endpoint. This lets you inspect exactly how the agent executed your request: which tools were called, what inputs they received, what outputs they produced, and whether they succeeded.

This is especially useful for:

  • Debugging or auditing agent behavior.
  • Understanding the sequence of actions taken by your agent.
  • Retrieving any artifacts (like images or scripts) generated during the run.
  • Sharing a transparent report of what happened during an automated workflow.

Retrieve Run Metadata​

GET /chat/run/{run_id}

Fetches the full trace of a run, including every step.

Response Example

Below is a sample response with multiple steps. Each step shows:

  • The tool (agent_name) used.
  • Its status (e.g., ok, failed).
  • The input it received.
  • The output it produced (including artifacts if any).
  • When it was executed (created_at).
{
  "status": "ok",
  "data": {
    "steps": [
      {
        "step_id": 1,
        "agent_name": "find_metadata",
        "status": "ok",
        "input": {
          "user_question": "Query Inc's best selling products"
        },
        "output": {
          "data": [
            []
          ]
        }
      },
      {
        "step_id": 2,
        "agent_name": "execute_sql",
        "status": "ok",
        "input": {
          "generated_sql": "SELECT ..."
        },
        "output": {
          "row_count": 5,
          "rows": [
            { "name": "Optimize Enterprise Schemas", "total_quantity_sold": 189 },
            ...
          ]
        }
      },
      {
        "step_id": 3,
        "agent_name": "create_graph",
        "status": "ok",
        "input": {
          "sql_results": "[...]",
          "chart_spec": "{...}"
        },
        "output": {
          "data": "Image created successfully.",
          "artifacts": [
            "tmp/image/...png",
            "tmp/script/...py"
          ]
        }
      },
      {
        "step_id": 4,
        "agent_name": "final_response",
        "status": "ok",
        "input": null,
        "output": {
          "content": "Here is the pie chart showing Query Inc's best-selling products: …"
        }
      }
    ]
  }
}

Understanding the Output​

Each step represents a single action (tool call) taken by the agent.

Step-by-step breakdown:​

  1. find_metadata
  • Looks up metadata relevant to the query in your virtual data lake(s).
  • Input: user's question.
  • Output: information and schema of relevant datasets.
  1. execute_sql
  • Runs the SQL generated from metadata lookup.
  • Input: SQL query.
  • Output: query result rows (with optional row count).
  1. create_graph
  • Visualizes the results in a chart.
  • Input: SQL results + chart specification.
  • Output: confirmation + artifacts (image & script paths).
  1. final_response
  • Produces the final, human-readable response back to the user.
  • Input: none.
  • Output: final message content.

Artifacts​

If a step produces artifacts (like .png or .py files), you'll find them listed under output.artifacts. These are file paths you can fetch and display or download.

Status​

Each step includes a status field:

  • ok — Step completed successfully.
  • Other values indicate failure or partial success.

The order of steps reflects the execution flow. You can use this trace to understand what happened at each point, spot bottlenecks, and retrieve outputs and intermediate data.