Forensics & Replay

SDK reference for routing replay and forensic snapshot methods.

TypeScript SDK

Replays

import BrainstormRouter from "brainstormrouter";

const client = new BrainstormRouter({ apiKey: "br_live_..." });

// List recent routing decisions
const { decisions, count } = await client.replays.decisions({
  limit: 50,
  since: "2026-03-01T00:00:00Z",
});

// Simulate alternative strategy
const simulation = await client.replays.simulate({
  strategy: "price",
  since: "2026-03-01T00:00:00Z",
  until: "2026-03-07T00:00:00Z",
});

// Compare strategies side-by-side
const comparison = await client.replays.compare({
  since: "2026-03-01T00:00:00Z",
});

client.replays.decisions(params?)

Param	Type	Default	Description
limit	number	100	Max decisions to return
since	string	last 24h	ISO 8601 start timestamp

Returns { decisions: ReplayDecision[], count: number }.

client.replays.simulate(params)

Param	Type	Required	Description
strategy	string	Yes	Strategy to simulate
since	string	No	ISO 8601 period start
until	string	No	ISO 8601 period end

Returns { period, actual, simulated } with cost and latency comparisons.

client.replays.compare(params?)

Param	Type	Default	Description
since	string	last 7d	ISO 8601 start timestamp

Returns { since, strategies: StrategyComparison[] }.

Forensic Snapshots

Forensic snapshots are accessed via the security resource. This endpoint requires a user JWT (Supabase session token), not an API key:

// Authenticated with a user JWT (e.g. from dashboard session)
const client = new BrainstormRouter({ apiKey: userJwt });

const { snapshots } = await client.security.forensicSnapshots();

Returns { snapshots: ForensicSnapshot[] } with agent termination proof-of-death records.

For API-key users, forensic snapshots are available via the MCP tool br_forensic_snapshots (requires security.read permission).

Python SDK

Replays

from brainstormrouter import BrainstormRouter

client = BrainstormRouter(api_key="br_live_...")

# List decisions
result = client.replays.decisions(limit=50, since="2026-03-01T00:00:00Z")

# Simulate
sim = client.replays.simulate(strategy="price", since="2026-03-01T00:00:00Z")

# Compare
comp = client.replays.compare(since="2026-03-01T00:00:00Z")

Async Python

from brainstormrouter import AsyncBrainstormRouter

client = AsyncBrainstormRouter(api_key="br_live_...")

result = await client.replays.decisions(limit=50)
sim = await client.replays.simulate(strategy="price")
comp = await client.replays.compare()

Forensic Snapshots

Requires a user JWT (not an API key):

# Authenticated with a user JWT
client = BrainstormRouter(api_key=user_jwt)

snapshots = client.security.forensic_snapshots()