What is a run record, and how do I read one?

A run record is the saved account of one workflow run: each step the AI employee visited, in order, what each step produced, and any failure along the way. You read it with the documented query workflowRuns(sessionId), signed in to your workspace, and it lets a person on your team check what the AI employee did, not only what it said.

Think of a technician’s job sheet: the customer hears “all fixed”; the sheet shows the work.

What counts as one run?

One run is one trip through the workflow, from a trigger to the point where it stops. A customer message is the usual trigger, so one conversation usually has several runs, and workflowRuns(sessionId) lists every run for that conversation, newest first.

A run waiting for the customer’s answer to a question shows AWAITING_INPUT. It is not broken: the answer continues it as a separate, linked run. Do not count it as a failure.

How do I read one?

Query workflowRuns with the conversation’s session id and look at each run’s status, error message and step list (nodeTrace).

query RunsForSession($sessionId: Int!) {
  workflowRuns(sessionId: $sessionId) {
    id
    status
    nodeTrace
    errorMessage
    totalTokensUsed
    createdAt
    completedAt
  }
}

errorMessage is filled in when the run failed; totalTokensUsed is that run’s model usage.

What does each step entry show?

One entry per step the run actually visited, in the order it ran. A step never reached has no entry, often the first clue when a branch “did not fire”. Each entry names the step and, where they apply, shows:

• The output: the variable the step wrote and its value. For a step that read a photo or a document, this is what it read.
• The request it sent: on steps that call another system, the request that went out, whether the call succeeded or not.
• The error: on a failed step, the reason, including a refusing system’s own response, so you see “missing field” rather than only “status 400”.
• Model usage and, on a step that answered from your knowledge base, which passages it retrieved.

Fields that do not apply are absent, so check for them rather than assume a default.

How does a failure show?

In two places: the failed step’s entry carries the error, and a run that stopped there carries an errorMessage. The customer sees a generic apology; the real reason is in the record. One subtlety: a step that calls another system can have a planned failure path, and then the run carries on and can finish normally with a failed step inside it. Read the steps, not only the run’s status.

How do I check a claim of “done”?

Match the reply against the step that should have done the work. If the AI employee told a customer “your application has been filed”, find the step that sends the application. Is it in the list? Did it fail? What did it send? The record cannot say whether the work was right, but it shows whether it happened and with what data, which a manager needs before trusting the reply. See also When an AI employee fails, what the customer sees.

What does the record protect?

It is built to avoid holding secrets, on a best-effort basis. Recognisable credentials such as tokens and keys are masked in recorded requests; a secret with no recognisable shape can still get through, so never write secrets into a step’s request. Signed file links are shown with their query string removed, and images a step fetches by link are not stored in the record at all. The changelog says where each of these is live.

Who can read run records?

A person signed in to your workspace. workflowRuns needs a signed-in user’s login; your backend’s API key and your front end’s short-lived session token cannot read it.

Run records are a debugging and supervision tool. The docs state no retention period, so keep your own copy of anything you need long term.

Related reference docs

• Observability: per-run inspection: every field of a step entry and what it means
• workflowRuns: the query, its arguments and an example response
• workflowRun: run statuses and the links between a paused run and its continuation
• Error handling: workflow run failures: how a failure inside a run differs from a refused request
• A run that is waiting is not a run that failed: why AWAITING_INPUT needs its own handling

To start reading your own runs, follow Observability & Debugging Your Agent.