Flow SDK

Execution Log

Every SDK artifact execution recorded — status, input/output, structured logs, timing, and full debug trace. Search, filter, and replay from one place.

The SDK Execution Log at SDK → Executions captures every invocation of every artifact across all trigger types: workflow nodes, scheduled jobs, webhook handlers, manual runs, and API calls. Use it to debug failures, measure performance, and audit data access.

Execution Record Schema

Field	Type	Description
id	varchar(26)	ULID. Prefixed exec_.
artifact_slug	varchar(100)	Artifact that was executed.
artifact_version	integer	Specific version that ran.
trigger_type	enum	workflow_node \| scheduled_job \| webhook \| manual \| api
trigger_id	varchar(26)	ID of the triggering entity (run ID, job ID, etc.).
status	enum	running \| completed \| failed \| timeout \| cancelled
input	jsonb	Input passed to the artifact (sanitized — secrets replaced with ***).
output	jsonb	Return value from the artifact.
error	jsonb	{ code, message, stack } if failed.
logs	jsonb	Array of { level, message, data, ts } structured log entries.
duration_ms	integer	Wall-clock execution time.
memory_peak_mb	integer	Peak memory usage.
started_at	timestamptz	Execution start time.
completed_at	timestamptz	Execution end time.
environment	enum	development \| staging \| production
workspace_id	varchar(26)	Owning workspace.

Filtering Executions

The execution log UI supports real-time filtering. The same filters are available via API:

bash

# All failed workflow-action executions
GET /api/flowsdk/executions
  ?executionType=workflow_action
  &success=false
  &limit=50

# Webhook-triggered executions
GET /api/flowsdk/executions
  ?triggerType=webhook
  &limit=50

# All executions against the incidents table
GET /api/flowsdk/executions
  ?tableName=incidents
  &limit=50

Structured Log Output

Logs written via ctx.log.* appear in each execution record in the logs array and are shown inline in the detail view:

json

"logs": [
  { "level": "info",  "message": "Script started",          "data": {},                     "ts": "2026-06-01T10:00:00.123Z" },
  { "level": "info",  "message": "Querying incidents",       "data": { "filter": {...} },    "ts": "2026-06-01T10:00:00.234Z" },
  { "level": "info",  "message": "Processing 42 records",   "data": { "count": 42 },        "ts": "2026-06-01T10:00:01.456Z" },
  { "level": "warn",  "message": "Skipped archived record",  "data": { "id": "inc_01HX..." },"ts": "2026-06-01T10:00:01.789Z" },
  { "level": "info",  "message": "Completed",               "data": { "processed": 41 },    "ts": "2026-06-01T10:00:02.001Z" }
]

Replaying Executions

Replay any past execution with its original input — useful for reproducing failures after a code fix:

bash

# Via UI: open the execution detail page → Replay button
# Via CLI:
flowos exec replay exec_01HX... --env production

# Replay with modified input
flowos exec replay exec_01HX... --input '{"incidentId": "inc_01HX..."}'

A replay creates a new execution record linked to the original via replay_of. The original execution is never modified.

API

GET

/api/flowsdk/executions

List executions across all artifacts, filtered by artifactType, executionType, success, triggerType, tableName, recordId, and limit.

GET

/api/flowsdk/artifacts/:id/executions

List executions for a specific artifact.

GET

/api/flowsdk/artifacts/:id/related-executions

List executions related to a specific record (requires ?recordId=).

Retention

•Execution records are retained for 90 days by default.
•Extend to 1 year on the Enterprise plan (Settings → Workspace → Data Retention).
•Execution logs for failed runs are always retained for the full period regardless of the default.

Performance Metrics

The SDK → Executions → Metrics tab shows per-artifact aggregate stats over a configurable time window:

•Invocation count, success rate, error rate
•p50, p95, p99 execution duration
•Peak and average memory usage
•Error breakdown by exception type
•Timeout rate over time

Set up an alert on sdk.execution.failed audit events via a webhook rule to get paged immediately when a production artifact fails, rather than waiting to notice it in the log.