Run trace reference

Location

Every workflow execution writes a JSON trace to:

~/.cori/runs/<run-key>/<utc-timestamp>.json

The run key encodes the workflow identity (path hash for local workflows, remote/<host>/<owner>/<repo>@<sha> for remote ones). The filename is the UTC timestamp of the run start in ISO 8601 format.

Reading traces

# List recent runs
cori runs list

# Show the full trace for a specific run
cori runs show <run-id>

Trace shape

{
  "run_id": "run_550e8400e29b41d4a716446655440000",
  "workflow_id": "translate-product-sheets-fr",
  "workflow_content_hash": "a1b2c3d4e5f6",
  "status": "completed",
  "trigger": "cli",
  "dry_run": false,
  "requesting_identity": "jean",
  "started_at": "2025-01-15T09:03:22.000Z",
  "ended_at": "2025-01-15T09:04:47.000Z",
  "duration_ms": 85000,
  "source": {
    "path": "./translate_product_sheets_fr"
  },
  "params": {
    "input_file": "products.csv",
    "spreadsheet_id": "1BxiM...",
    "dry_run": false
  },
  "activities": [
    {
      "activity_id": "activity-001",
      "step_name": "01_read_source_rows",
      "kind": "cli",
      "status": "completed",
      "started_at": "2025-01-15T09:03:23.000Z",
      "ended_at": "2025-01-15T09:03:24.500Z",
      "duration_ms": 1500,
      "attempts": 1,
      "route": null,
      "task_queue": "cori.user.john",
      "worker_identity": "Person",
      "input_summary": { },
      "output_summary": { },
      "output": { },
      "cost_eur": 0.0,
      "tokens": null,
      "error": null,
      "notes": null
    }
  ],
  "cost": {
    "total_eur": 0.15,
    "input_tokens": 2048,
    "output_tokens": 512
  },
  "error": null
}

Top-level RunTrace fields

Field	Type	Description
`run_id`	String	Unique run identifier (formatted as `run_<uuid>`), used with `cori runs show`
`workflow_id`	String	Value of `id` from the manifest
`workflow_content_hash`	String \| null	16-hex-char hash of the workflow folder contents at run time
`status`	String	`completed` or `failed`
`trigger`	String	How the run was initiated (typically `cli`)
`dry_run`	Boolean	Whether the run executed in dry-run mode
`requesting_identity`	String \| null	Identity (user or pool name) of the machine/user that ran `cori run`
`started_at`	ISO 8601	Run start time (UTC)
`ended_at`	ISO 8601	Run end time (UTC)
`duration_ms`	Number	Total elapsed time in milliseconds
`source`	Object \| null	Origin of the workflow: `{ path }` for local, extended for remote workflows (Phase 7+)
`params`	Object	Parameter values used for this run
`activities`	Array	Per-step activity traces
`cost`	CostSummary	Total LLM token costs and token usage
`error`	String \| null	Error message if the run failed, otherwise `null`

CostSummary object

Field	Type	Description
`total_eur`	Number	Total cost in EUR for all LLM activities
`input_tokens`	Number	Total input tokens consumed across all LLM activities
`output_tokens`	Number	Total output tokens consumed across all LLM activities

ActivityTrace fields

Field	Type	Description
`activity_id`	String	Unique activity identifier within the run
`step_name`	String	Step filename without the `.ts` extension
`kind`	String	Activity kind: `cli`, `mcp_tool`, `code`, or `llm`
`status`	String	`completed` or `failed`
`started_at`	ISO 8601	Activity start time (UTC)
`ended_at`	ISO 8601	Activity end time (UTC)
`duration_ms`	Number	Elapsed time in milliseconds
`attempts`	Number	Number of attempts made (retries + 1)
`route`	String \| null	Route hint if explicitly set by the step (usually `null`)
`task_queue`	String \| null	Temporal task queue the activity was dispatched to (Phase 7+, `null` for legacy traces)
`worker_identity`	WorkerIdentity \| null	Type/identity of the worker that executed this activity (Phase 7+)
`input_summary`	Object	Abbreviated activity input for readability
`output_summary`	Object	Abbreviated activity output for readability
`output`	Object	Complete activity output (matches step's `output` Zod schema)
`cost_eur`	Number \| null	Cost of this activity in EUR (LLM activities only; `null` otherwise)
`tokens`	TokenUsage \| null	Token usage breakdown if applicable
`error`	String \| null	Error message if the activity failed, otherwise `null`
`notes`	String \| null	Additional diagnostic notes, otherwise `null`

Key differences from documentation

When authoring workflows, keep these implementation details in mind:

Field naming: Use ended_at not completed_at; params not parameters; step_name not step
Remote workflows: The source field structure differs from workflow_ref; check actual runs for the current format
No top-level result: Workflow result is reconstructed from the final activity outputs; not a separate field
Phase 7 fields: task_queue and worker_identity are present in recent runs but null in legacy traces
Cost tracking: Only LLM activities populate cost_eur; CLI and code activities have null