Source: https://docs.cumuluslabs.io/investigate-runs
Content version: 1e571a21

# Investigate a run from decision to delivery

Use run review to find which version executed, trace a branch decision and check whether an external action was sent. This guide follows a billing-support call through its transcript, timeline and HTTP receipts.

The screenshots show Studio with synthetic run records, costs and timings. Select any screenshot to open it at full size.

## Open the run {#start}

![The run review showing a billing-support transcript and the selected run](https://docs.cumuluslabs.io/docs-assets/run-review.png)

Open **Calls & runs**, choose the channel and select a run. Record its run ID, publication version and terminal state before investigating individual messages.

| Question | Where to look | API |
| --- | --- | --- |
| Which definition ran? | Details and the publication | [Get a run](/docs/reference/runs.get) |
| What did the caller and agent say? | Transcript | [Get a transcript](/docs/reference/runs.transcript) |
| What happened in sequence? | Timeline | [Run events](/docs/reference/runs.events) |
| What external actions were attempted? | Tool calls | [Action receipts](/docs/reference/runs.effects) |
| What business fields were extracted? | Analysis | [Run analysis](/docs/reference/runs.analysis) |
| What usage was measured? | Usage & cost | [Run usage](/docs/reference/runs.usage) |
| What did a cloud task return? | Result | [Task result](/docs/reference/runs.result) |

Keep transport, execution and business outcomes distinct. A connected phone call can still fail its task. A completed execution can still leave a business outcome unknown. An admitted run is not a completed run.

## Triage different outcomes in one workspace {#triage}

![Resolved, review, voicemail and failed runs shown together in the operating view](https://docs.cumuluslabs.io/docs-assets/operations-run-list.png)

Use the run list to select the right investigation. A voicemail, an infrastructure failure, a human conversation requiring review and a confirmed resolution need different next actions. Filter by the channel, state and time window, then keep the run ID when escalating the issue.

Check the business outcome before closing a case. An ended call may still need review.

## Identify the version and its context {#identity}

![A selected run's publication and detailed outcome/context records](https://docs.cumuluslabs.io/docs-assets/operations-run-identity.png)

Open Details before changing today's draft. The run's publication pins the definition that executed. Use the original case/order reference to find the business operation; a similar transcript or caller name is not a reliable identifier.

When two runs behave differently, compare their publications and admission context before assuming the model changed its mind under identical conditions. Keep the action's effect identity as well as the run identity when investigating a downstream write.

## Follow the event history {#timeline}

![The run timeline showing node entries and the run ending](https://docs.cumuluslabs.io/docs-assets/run-timeline.png)

*The timeline shows the ordered events recorded for this run. This synthetic example enters identification, verification, lookup and invoice explanation before ending.*

Use the timeline to locate the decision around an unexpected message or action:

1. Find the node entered just before the behavior.
2. Check its predecessor and transition. A model-selected conversation edge and an action-result edge explain different causes.
3. Open the publication that ran and inspect the relevant node. Editing today's draft does not change what an older run executed.
4. Check adjacent events and action receipts before assuming that a node entry proves a side effect succeeded.

For integrations, `runs.events` provides the durable event history and an SSE stream. Retain the sequence cursor when reconnecting. The run remains the identity you use for transcript, analysis and receipts, so you do not need to invent separate correlation IDs for each product surface.

## Distinguish an attempted action from a delivered action {#receipts}

![An expanded account lookup showing two HTTP send attempts alongside a denied webhook](https://docs.cumuluslabs.io/docs-assets/run-tool-receipts.png)

*The example lookup receives HTTP 500 and then HTTP 200. The denied webhook is listed separately.*

![An expanded webhook receipt showing policy denial and that nothing was sent](https://docs.cumuluslabs.io/docs-assets/run-denied-action.png)

*The denied action has no HTTP send. A policy refusal is different from an endpoint returning an error.*

Read these fields together:

| Evidence | What it establishes | What it does not establish |
| --- | --- | --- |
| Policy decision: allow | This attempt passed the platform's action policy check | Your downstream system accepted the business operation |
| Policy decision: deny, zero sends | The platform refused the action before sending it | An endpoint outage or an HTTP rejection |
| Send attempts and HTTP receipts | Which HTTP responses were observed and their timing | A business transaction committed correctly unless the response contract says so |
| Unknown outcome | Delivery or completion cannot safely be concluded | That nothing happened |

If an action was denied, inspect the reason and correct the intended destination or access configuration. If the endpoint returned an error, investigate that endpoint and its request contract. If the outcome is unknown, reconcile with the downstream system or retry only under the supported idempotency contract.

Cumulus records policy decisions, send attempts and receipts with the run. Your business service remains responsible for enforcing its own permissions and for making repeated write requests safe. The platform is not a substitute for a transactional contract at the destination.

## Reconcile an uncertain write {#uncertain}

![An uncertain HTTP action with its effect identity and idempotency key](https://docs.cumuluslabs.io/docs-assets/operations-uncertain-action.png)

This example asks for a refund after verification, eligibility and explicit confirmation. The HTTP outcome is uncertain. The agent states that it cannot confirm completion and sends the case for review.

Read the effect key and check the transaction at the business service. A timeout can occur after the service committed the operation. Sending the write again under a new key risks a second transaction.

The receipt retains the uncertain state and effect identity. Use your service’s transaction lookup and retry contract to resolve it.

## Review the executed path {#path}

![The run's node path rendered over its publication flow](https://docs.cumuluslabs.io/docs-assets/operations-run-path.png)

Use Node path to see which parts of the published graph were visited. Compare it with the expected route: verification, eligibility, confirmation, the write and the fallback. A node visit identifies execution structure; check the related action receipt before claiming the write succeeded.

## Use the same run model for a cloud task {#cloud}

![A cloud task result showing typed support-triage fields alongside its run details](https://docs.cumuluslabs.io/docs-assets/cloud-task-result.png)

*This synthetic task returns an account reference, request type, proposed next step and escalation flag. No phone connection is involved.*

For an API-triggered support-triage task, configure the agent's cloud input and output schemas, publish it, then admit a cloud task with the case data as input. Wait for completion and read the result state before handing the returned fields to another system. A proposed next step is data, not evidence that the next action was performed.

Cloud and phone runs use the same publication and run IDs. Read the task’s result, events, action receipts and usage through the run API.

Start with [cloud task execution](/docs/api#cloud-run) and [triggers](/docs/triggers-and-webhooks) if a schedule should start the work. Your integration still validates business inputs and decides what downstream actions it will authorize.

## Review analysis and cost {#analysis}

![A run's measured usage and cost alongside analysis fields](https://docs.cumuluslabs.io/docs-assets/operations-run-usage.png)

*This display uses synthetic measurements. It illustrates where to inspect tokens, connected time, completeness and the extracted next step.*

Read extracted analysis as a separate output: an unavailable or still-processing analysis is different from a negative business result. Check whether a recording was requested and retained before expecting a playable artifact; recording links expire.

Usage may be complete, incomplete or unpriced. Do not treat a missing price as zero spend. [Run usage](/docs/reference/runs.usage) exposes completeness along with the measurements; [workspace usage](/docs/operations#usage) aggregates the organization view.

Use service logs and traces to investigate infrastructure failures. Confirm the business result through the run’s action receipts and your downstream service.

## Turn an incident into a test {#regression}

Write down the observed failure, expected behavior, node path and external response that triggered it. Add a case to the [regression suite](/docs/regression-testing), mock the relevant action and test a new publication before promotion.

For example, add a case where the caller asks for invoice details before verification. Assert that the lookup node is not visited before authorization, and use a judged criterion to check that the conversation does not disclose account details.