> ## Documentation Index
> Fetch the complete documentation index at: https://wuweism.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Counterfactual traces

> Retrieve counterfactual trace records produced by Wu-Weism's causal reasoning pipeline.

A counterfactual trace is a structured audit record created each time Wu-Weism evaluates a counterfactual query — "what would have happened to `outcome` had `variable` been set to `value`?" Traces capture the full provenance of that reasoning: the SCM used, the intervention applied, the adjustment set, the causal assumptions, and the AI provider that executed the analysis.

Traces are immutable once created. You can retrieve them by `traceId` to inspect past reasoning, attach them to claims, or audit your causal workflow.

***

## Get a counterfactual trace

```
GET /api/scm/counterfactual-traces/{traceId}
```

<Note>
  This endpoint requires authentication. Include your session token in the `Authorization` header.
</Note>

### Path parameters

<ParamField path="traceId" type="string" required>
  UUID of the counterfactual trace to retrieve. Trace IDs are returned when counterfactual analyses are run through the causal chat or hybrid synthesize pipelines.
</ParamField>

### Response fields

<ResponseField name="traceId" type="string" required>
  UUID of the trace. Matches the `traceId` supplied in the request path.
</ResponseField>

<ResponseField name="modelRef" type="object" required>
  Reference to the SCM used for this counterfactual evaluation.

  <Expandable title="modelRef properties" defaultOpen={true}>
    <ResponseField name="modelKey" type="string">
      Unique identifier of the SCM. Corresponds to a key in the [model registry](/api/scm/models).
    </ResponseField>

    <ResponseField name="version" type="string">
      Version of the SCM that was active when the trace was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="intervention" type="object" required>
  The causal intervention that was evaluated.

  <Expandable title="intervention properties" defaultOpen={true}>
    <ResponseField name="variable" type="string">
      The variable that was set by the do-operator (e.g., `"cortisol_level"`).
    </ResponseField>

    <ResponseField name="value" type="string | number | boolean">
      The value assigned to the intervention variable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="outcome" type="string" required>
  The outcome variable evaluated under the intervention.
</ResponseField>

<ResponseField name="method" type="string" required>
  The algorithmic method used to compute the counterfactual. Currently `"deterministic_graph_diff"` for all traces — this method computes the counterfactual by propagating the intervention through the SCM's directed acyclic graph and diffing the resulting outcome distribution against the factual.
</ResponseField>

<ResponseField name="assumptions" type="string[]" required>
  List of causal assumptions that were active during evaluation (e.g., `"acyclicity"`, `"no unmeasured confounding"`, `"stable unit treatment value assumption"`).
</ResponseField>

<ResponseField name="adjustmentSet" type="string[]" required>
  Variables conditioned on to satisfy the identifiability criterion. Corresponds to the confirmed adjustment set from intervention validation.
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Execution metadata for the trace.

  <Expandable title="metadata properties" defaultOpen={true}>
    <ResponseField name="providerId" type="string">
      AI provider used to generate the causal reasoning (e.g., `"anthropic"`, `"openai"`, `"gemini"`).
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of when the trace was created (e.g., `"2026-03-12T14:22:05Z"`).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://wuweism.com/api/scm/counterfactual-traces/b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19 \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript JavaScript theme={null}
  const traceId = 'b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19';

  const response = await fetch(
    `https://wuweism.com/api/scm/counterfactual-traces/${traceId}`,
    {
      headers: { 'Authorization': 'Bearer <token>' },
    }
  );

  const trace = await response.json();
  ```

  ```python Python theme={null}
  import requests

  trace_id = 'b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19'

  response = requests.get(
      f'https://wuweism.com/api/scm/counterfactual-traces/{trace_id}',
      headers={'Authorization': 'Bearer <token>'},
  )

  trace = response.json()
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "traceId": "b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19",
    "modelRef": {
      "modelKey": "neural_topology_v1",
      "version": "1.0.0"
    },
    "intervention": {
      "variable": "cortisol_level",
      "value": "high"
    },
    "outcome": "hippocampal_volume",
    "method": "deterministic_graph_diff",
    "assumptions": [
      "acyclicity",
      "no unmeasured confounding given adjustment set",
      "stable unit treatment value assumption (SUTVA)",
      "faithfulness"
    ],
    "adjustmentSet": ["stress_exposure"],
    "metadata": {
      "providerId": "anthropic",
      "timestamp": "2026-03-12T14:22:05Z"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Trace not found"
  }
  ```
</ResponseExample>

<Info>
  Traces are scoped to your account. You can only retrieve traces created within your own sessions. Attempting to access another user's trace returns `404 Not Found`.
</Info>