Skip to main content
Use client.runs.steps(run_id) to inspect step results.

​
Step response shape (v1)

trace = client.runs.steps(run_id)
print(trace.keys())  # dict_keys(["run", "steps"])
Each step object in v1 includes:
FieldType
idstr
titlestr
kindstr
statusstr
depends_onlist[str]
output_flatdict
output_flat is the public normalized output payload for SDK/v1 consumers.

​
output_flat core fields

FieldTypeNotes
output_flat_versionintCurrently 1
typetext, json, media, tool_calls, or noneNormalized output type
primaryAnyMain value for the type
usagedictToken/cost fields when available
finish_reasonstrNormalized finish reason
Additional fields may appear, e.g. schema_urn, schema_name, warnings.

​
Example: text output

for step in trace["steps"]:
    flat = step["output_flat"]
    if flat.get("type") == "text":
        print(flat["primary"])

​
Example: structured/json output

for step in trace["steps"]:
    flat = step["output_flat"]
    if flat.get("type") == "json":
        data = flat["primary"]
        print(data)

​
Example: failed steps

for step in trace["steps"]:
    if step["status"] == "failed":
        print("failed step", step["id"], step["title"])
        print(step["output_flat"])

​
REST API v1

GET /v1/runs/{run_id}/steps/
Authorization: Bearer <api-key>
Example shape: 
{
  "run": {"id": "01JRUN..."},
  "steps": [
    {
      "id": "step_1",
      "title": "Summarize",
      "kind": "llm_simple",
      "status": "done",
      "depends_on": [],
      "output_flat": {
        "output_flat_version": 1,
        "type": "text",
        "primary": "Summary text",
        "usage": {
          "input_tokens": 120,
          "output_tokens": 80,
          "total_tokens": 200,
          "cost": 0.05
        },
        "finish_reason": "stop"
      }
    }
  ]
}

​
See also