Events

Every significant action during a workflow run is recorded as an event. Events provide a complete audit trail of execution -- step starts, completions, failures, retries, and more.

List Events for a Workflow Run

GET /v1/workflow-runs/:id/events

Returns a paginated list of events for a specific workflow run, ordered chronologically (oldest first).

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number (min 1)
`pageSize`	`integer`	`20`	Results per page (1-100)

Example Request

curl "https://api.stevora.dev/v1/workflow-runs/wfrun_def456/events?page=1&pageSize=50" \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "evt_001",
      "workflowRunId": "wfrun_def456",
      "stepRunId": null,
      "eventType": "WORKFLOW_STARTED",
      "payload": {},
      "createdAt": "2026-04-02T12:00:00.000Z"
    },
    {
      "id": "evt_002",
      "workflowRunId": "wfrun_def456",
      "stepRunId": "srun_aaa111",
      "eventType": "STEP_STARTED",
      "payload": {
        "stepName": "enrich-company",
        "stepType": "task"
      },
      "createdAt": "2026-04-02T12:00:01.000Z"
    },
    {
      "id": "evt_003",
      "workflowRunId": "wfrun_def456",
      "stepRunId": "srun_aaa111",
      "eventType": "STEP_COMPLETED",
      "payload": {
        "stepName": "enrich-company",
        "durationMs": 1523
      },
      "createdAt": "2026-04-02T12:00:02.523Z"
    },
    {
      "id": "evt_004",
      "workflowRunId": "wfrun_def456",
      "stepRunId": "srun_bbb222",
      "eventType": "STEP_STARTED",
      "payload": {
        "stepName": "generate-welcome-email",
        "stepType": "llm"
      },
      "createdAt": "2026-04-02T12:00:03.000Z"
    },
    {
      "id": "evt_005",
      "workflowRunId": "wfrun_def456",
      "stepRunId": "srun_bbb222",
      "eventType": "LLM_CALL_COMPLETED",
      "payload": {
        "model": "gpt-4o",
        "inputTokens": 245,
        "outputTokens": 312,
        "costUsd": 0.0087
      },
      "createdAt": "2026-04-02T12:00:05.100Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 5,
    "totalPages": 1
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid query parameters
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Workflow run not found or belongs to another workspace

Event Types

Events use the following eventType values:

Workflow-level Events

Event Type	Description
`WORKFLOW_STARTED`	The workflow run began execution
`WORKFLOW_COMPLETED`	All steps completed successfully
`WORKFLOW_FAILED`	The workflow terminated due to a step failure
`WORKFLOW_CANCELLED`	The workflow was cancelled via the API

Step-level Events

Event Type	Description
`STEP_STARTED`	A step began execution
`STEP_COMPLETED`	A step finished successfully
`STEP_FAILED`	A step failed (may trigger retry)
`STEP_RETRYING`	A failed step is being retried

LLM Events

Event Type	Description
`LLM_CALL_STARTED`	An LLM API call was initiated
`LLM_CALL_COMPLETED`	An LLM API call completed with token/cost data
`LLM_CALL_FAILED`	An LLM API call failed
`LLM_FALLBACK_TRIGGERED`	Primary model failed; falling back to next model
`GUARDRAIL_TRIGGERED`	A guardrail check failed on the LLM response
`TOOL_CALL_EXECUTED`	An LLM tool call was executed

Approval Events

Event Type	Description
`APPROVAL_REQUESTED`	An approval step is waiting for a decision
`APPROVAL_DECIDED`	An approval decision was submitted

Signal Events

Event Type	Description
`SIGNAL_RECEIVED`	An external signal was delivered to a waiting run

Event Payload

The payload object varies by event type. Common fields include:

Field	Present In	Description
`stepName`	Step events	Name of the step
`stepType`	`STEP_STARTED`	Type of the step (`task`, `llm`, `approval`, etc.)
`durationMs`	`STEP_COMPLETED`	Step execution time in milliseconds
`error`	`STEP_FAILED`, `LLM_CALL_FAILED`	Error message
`model`	LLM events	Model name used for the call
`inputTokens`	`LLM_CALL_COMPLETED`	Number of input tokens
`outputTokens`	`LLM_CALL_COMPLETED`	Number of output tokens
`costUsd`	`LLM_CALL_COMPLETED`	Cost of the LLM call in USD
`decision`	`APPROVAL_DECIDED`	The approval decision (`approved`, `rejected`, `edited`)
`signalType`	`SIGNAL_RECEIVED`	The type of signal received

Events

On this page