---
title: "Trace event causality"
method: GET
path: "/v1/events/{id}/trace"
tags: ["Events"]
---

# Trace event causality

`GET /v1/events/{id}/trace`

Get the full causality context for an event in a single API call.

Returns:
- **ancestors**: Parent chain from root to this event's parent
- **children**: Direct child events caused by this event
- **retryChain**: Original event and all retry attempts
- **anomalies**: Detected anomalies linked to this event
- **summary**: Quick stats (counts, hasFailures flag)

**Query Parameters:**
- `format=tree` - Returns ASCII tree output for CLI/support tickets

This is the primary debugging endpoint for tracing errors through the ledger.

**Example use case**: Customer reports "my run failed at step 5"
```
GET /v1/events/{failingEventId}/trace
GET /v1/events/{failingEventId}/trace?format=tree
```
Returns the complete context: what led to this event, what it triggered,
whether it was retried, and any anomalies detected.

## Path parameters

- `id` string, required

## Query parameters

- `format` 'json' | 'tree'

## Response `200`

Full event trace with causality context

- object — Full event trace with causality context
  - `event` object — The event being traced (full details)
    - `id` string
    - `eventType` 'USAGE' | 'API_CALL' | 'LLM_INFERENCE' | 'TOOL_CALL' | 'DATABASE' | 'FILE_IO' | 'NETWORK' | 'DECISION' | 'HUMAN_IN_LOOP' | 'MEMORY' | 'CUSTOM' | 'TOOL_CALL_START' | 'TOOL_CALL_END' | 'TOOL_CALL_ERROR' | 'TOOL_CALL_RETRY' | 'TRAINING' | 'FINE_TUNING'
    - `actionName` string
    - `outcome` 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'SKIPPED' | 'RETRIED' | 'TIMEOUT' | 'CANCELLED'
    - `explanation` string, nullable
    - `idempotencyKey` string, nullable
    - `customerId` string
    - `runId` string, nullable
    - `workflowId` string, nullable
    - `parentEventId` string, nullable
    - `retryOfEventId` string, nullable
    - `attemptNumber` integer
    - `createdAt` string, date-time
    - `inputHash` string, nullable
    - `outputHash` string, nullable
    - `childEvents` string[]
    - `retriedBy` string, nullable
    - `chargeId` string, nullable
    - `costUsdc` string, nullable
    - `usageType` string, nullable
    - `quantity` string, nullable
    - `units` string, nullable
    - `description` string, nullable
    - `metadata` object, nullable
    - `spanKind` string, nullable
    - `inputBytes` integer, nullable
    - `outputBytes` integer, nullable
    - `queueDurationMs` integer, nullable
    - `executionDurationMs` integer, nullable
    - `startedAt` string, date-time, nullable
    - `endedAt` string, date-time, nullable
    - `errorType` string, nullable
    - `errorMessage` string, nullable
    - `errorStack` string, nullable
    - `retryCount` integer, nullable
    - `retryBackoffMs` integer, nullable
    - `retryReason` string, nullable
  - `ancestors` object[] — Parent chain from root to parent (ordered root → parent)
    - `id` string
    - `eventType` string
    - `actionName` string
    - `outcome` string
    - `explanation` string, nullable
    - `attemptNumber` integer
    - `createdAt` string, date-time
    - `costUsdc` string, nullable
  - `children` object[] — Direct child events
    - `id` string
    - `eventType` string
    - `actionName` string
    - `outcome` string
    - `explanation` string, nullable
    - `attemptNumber` integer
    - `createdAt` string, date-time
    - `costUsdc` string, nullable
  - `retryChain` object — Retry chain if this event was retried or is a retry
    - `originalEvent` object, nullable — The original event that was retried
    - `retries` object[] — All retry attempts ordered by attemptNumber
  - `anomalies` object[] — Anomalies linked to this event or its retry chain
    - `id` string
    - `anomalyType` string
    - `severity` string
    - `detectedAt` string, date-time
    - `status` string
    - `metric` string, nullable
    - `expectedValue` string, nullable
    - `actualValue` string, nullable
  - `summary` object — Quick summary statistics
    - `totalAncestors` integer
    - `totalChildren` integer
    - `totalRetries` integer
    - `totalAnomalies` integer
    - `hasFailures` boolean — True if any event in trace has FAILURE outcome

## Other responses

- `401` — Unauthorized
- `404` — Event not found

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/versions/2cb1567969ca/schema)