Chronicle Labs API is currently in beta. Reach out for access

API REFERENCE

Traces

Agent traces are the full execution logs - what the agent saw and did. Chronicle evaluates traces to detect failures and generate structured correction artifacts.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

Endpoints

Method	Path	Status
`POST`	`/v1/traces`	Beta
`GET`	`/v1/traces`	Beta
`GET`	`/v1/traces/{id}`	Beta
`POST`	`/v1/traces/{id}/labels`	Beta
`GET`	`/v1/traces/{id}/artifacts`	Beta

The trace object

A trace captures the complete behavioral record of an agent execution: the workflow event it received, the context passed to the model, reasoning steps, tool calls, sequence and timing, and the final outcome.

Traces are the input to Chronicle's evaluation pipeline. They are not the product - they are the evidence. Artifacts are the improvement output.

workflow_event - the trigger event (ticket, refund, CRM update).
model_context - full prompt and context window sent to the model.
steps - ordered list of reasoning steps, tool calls, and intermediate results.
outcome - the agent's final action or response.
metadata - timing, token usage, model version, sandbox ID.

Submit a trace

Submit a trace after an agent completes execution. Chronicle vectorizes it, compares against historical behavior, and flags out-of-pattern executions for verification.

tenant_idstringrequired

Tenant namespace.

agent_idstringrequired

Identifier for the agent under test.

sandbox_idstring

Sandbox this execution ran in.

workflow_eventobjectrequired

The trigger event the agent received.

model_contextobject

Prompt and context window passed to the model.

stepsobject[]required

Ordered list of execution steps. Each step has type (reasoning, tool_call, observation), content, and timestamp.

outcomeobjectrequired

Final action or response produced by the agent.

metadataobject

Timing, token usage, model version, and other execution metadata.

Node

const trace = await chronicle.traces.create({
  tenant_id: "tenant_demo",
  agent_id: "refund_agent_v2",
  sandbox_id: "sandbox_001",
  workflow_event: {
    event_type: "ticket.refund_requested",
    conversation_id: "ticket_4821",
    payload: { order_id: "order_1001", reason: "damaged_item", amount: 4999 },
  },
  steps: [
    { type: "reasoning", content: "Customer requests refund for damaged item. Policy allows full refund.", timestamp: "2026-02-21T10:30:01Z" },
    { type: "tool_call", content: 'refund_api.create({ order_id: "order_1001", amount: 4999 })', timestamp: "2026-02-21T10:30:02Z" },
    { type: "observation", content: "Refund created: ref_abc123", timestamp: "2026-02-21T10:30:03Z" },
  ],
  outcome: { action: "refund_issued", refund_id: "ref_abc123", amount: 4999 },
  metadata: { model: "gpt-4o", tokens_used: 847, latency_ms: 2340 },
});

Response

JSON

{
  "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "status": "received",
  "evaluation": "pending",
  "message": "Trace submitted for evaluation"
}

List traces

Query traces with filters. Results include evaluation status and summary verdicts.

tenant_idstringrequired

Tenant namespace.

agent_idstring

Filter by agent.

statusenum

Filter by evaluation status: "pending", "passed", "failed", "skipped".

sandbox_idstring

Filter by sandbox.

limitinteger

Max traces to return (default 25, max 1000).

offsetinteger

Number of results to skip (default 0).

Node

const traces = await chronicle.traces.list({
  tenant_id: "tenant_demo",
  agent_id: "refund_agent_v2",
  status: "failed",
  limit: 20,
});

Response

JSON

{
  "traces": [
    {
      "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
      "agent_id": "refund_agent_v2",
      "status": "failed",
      "verdict": "out_of_policy_refund",
      "created_at": "2026-02-21T10:30:00Z",
      "step_count": 3
    }
  ],
  "count": 1,
  "has_more": false
}

Retrieve a trace

Get the full trace including all execution steps, evaluation status, and verdict.

Node

const trace = await chronicle.traces.retrieve("trc_01J8XNR3KMPQ2VWYZ");

Response

JSON

{
  "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "tenant_id": "tenant_demo",
  "agent_id": "refund_agent_v2",
  "sandbox_id": "sandbox_001",
  "status": "failed",
  "verdict": "out_of_policy_refund",
  "workflow_event": { "event_type": "ticket.refund_requested", "conversation_id": "ticket_4821" },
  "steps": [
    { "type": "reasoning", "content": "Customer requests refund...", "timestamp": "2026-02-21T10:30:01Z" },
    { "type": "tool_call", "content": "refund_api.create(...)", "timestamp": "2026-02-21T10:30:02Z" },
    { "type": "observation", "content": "Refund created: ref_abc123", "timestamp": "2026-02-21T10:30:03Z" }
  ],
  "outcome": { "action": "refund_issued", "refund_id": "ref_abc123", "amount": 4999 },
  "metadata": { "model": "gpt-4o", "tokens_used": 847, "latency_ms": 2340 },
  "created_at": "2026-02-21T10:30:00Z"
}

Submit labels

Human reviewers submit labels for a trace. Labels feed Chronicle's verifier pipeline and determine whether a failure becomes a correction artifact.

verdictenumrequired

"pass", "fail", or "skip".

reasonstring

Human explanation for the verdict.

tagsstring[]

Classification tags, e.g. out_of_policy, hallucination, wrong_tool.

Node

await chronicle.traces.label("trc_01J8XNR3KMPQ2VWYZ", {
  verdict: "fail",
  reason: "Agent issued refund above policy limit without escalation",
  tags: ["out_of_policy", "missing_escalation"],
});

Response

JSON

{
  "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "label_id": "lbl_01J8XP4QRMST",
  "verdict": "fail",
  "artifact_generation": "queued"
}

Get correction artifacts

After a trace is labeled as failed and verified, Chronicle generates structured correction artifacts. Artifacts contain the failure description, expected behavior, and a machine-readable correction that developers use to fix the agent before go-live.

Node

const artifacts = await chronicle.traces.artifacts("trc_01J8XNR3KMPQ2VWYZ");

Response

JSON

{
  "trace_id": "trc_01J8XNR3KMPQ2VWYZ",
  "artifacts": [
    {
      "artifact_id": "art_01J8XQZW9NKV",
      "type": "correction",
      "failure": {
        "description": "Agent issued a $49.99 refund without manager escalation",
        "tags": ["out_of_policy", "missing_escalation"],
        "step_index": 1
      },
      "expected_behavior": "Refunds above $25 require escalation to a manager before processing",
      "correction": {
        "rule": "If refund amount > 2500 cents, call escalation_api.request_approval() before refund_api.create()",
        "confidence": 0.94
      },
      "created_at": "2026-02-21T10:35:00Z"
    }
  ],
  "count": 1,
  "has_more": false
}