---
title: "Append Workflow Progress Event"
method: POST
path: "/api/workflow-runs/{run_id}/progress"
tags: ["plays"]
---

# Append Workflow Progress Event

`POST /api/workflow-runs/{run_id}/progress`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/workflow-runs/{run_id}/progress`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Path parameters

- `run_id` string, required

## Request body

- CanonicalProgressWriteRequest: One idempotent canonical progress update from a hosted Workflow Play.
  - `child_operation_id` string, nullable: Distinct child operation id for workflow-step progress only.
  - `completed` integer, nullable: Completed work units.
  - `detail` string, nullable: Optional bounded human-facing progress detail.
  - `event_id` string, required: Stable idempotency identity for this exact progress event.
  - `label` string, required: Short human-facing operation label.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed' | 'cancelled', required: Canonical operation lifecycle state.
  - `terminal` boolean: True exactly for completed, failed, or cancelled status.
  - `total` integer, nullable: Total work units; valid only with completed.

## Response `200`

Successful Response

- CanonicalProgressWriteResponse: Receipt containing the exact persisted canonical progress event.
  - `event` object, required: Persisted or idempotently adopted progress event.
    - `activity_kind` string, nullable: Stable activity classification when one was provided.
    - `completed` integer, nullable: Completed work units.
    - `detail` string, nullable: Optional human-facing progress detail.
    - `event_id` string, required: Caller-supplied idempotent event identity.
    - `label` string, required: Short human-facing operation label.
    - `occurred_at` string, required: RFC 3339 event time assigned by the server.
    - `operation_id` string, required: Operation whose progress changed.
    - `parent_operation_id` string, nullable: Immediate parent operation identity when nested.
    - `root_operation_id` string, nullable: Root operation identity for the progress tree.
    - `sequence` integer, required: Server-assigned monotonic stream sequence.
    - `source_sequence` integer, nullable: Upstream sequence paired with source_stream_id.
    - `source_stream_id` string, nullable: Upstream stream identity when this event mirrors another stream.
    - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed' | 'cancelled', required: Canonical operation lifecycle state.
    - `stream_id` string, required: Canonical Workflow Play progress stream id.
    - `surface` 'status' | 'task', nullable: Preferred client presentation surface.
    - `terminal` boolean, required: Whether this event terminalizes the operation.
    - `total` integer, nullable: Total work units.
    - `version` 1, required: Canonical progress protocol version.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)