API

Get workflows events (GET /api/workflows/{workflowId}/runs/{runId}/events/stream)

Get workflows events. This reads the current tenant or platform state without changing the resource.

Applies to: Next (0.1 RC1 Preview)
Product revision: 25748655d6be
Audience: Developers and integrators
Source reviewed: 2026-10-06

GET/api/workflows/{workflowId}/runs/{runId}/events/stream

Preview

Get workflows events. This reads the current tenant or platform state without changing the resource.

Operation ID getapiWorkflowsWorkflowIdRunsRunIdEventsStream

Operation details

Purpose

Get workflows events. This reads the current tenant or platform state without changing the resource.

When to use it

Use this while monitoring a run when a streamed terminal or waiting state update is more appropriate than repeated polling.

When not to use it

Do not use this as a historical event query or assume replay beyond the documented stream lifecycle. Read the run or event list operation instead.

Contract

Availability

Product version: Next Product release
Licence: An active Product licence is required except for health, authentication, and licence remediation operations.
Entitlements: workflow.enabled
Service roles: workflow
Deployment: customer managed installation
Feature state: preview

Security

Access

Sign in: Use a session cookie or Bearer session token.

Actor: Authenticated Pūnaha actor authorised for the selected tenant and resource
Permission: workflows.read
Resource: workflow / execute / example workflowid
Tenant rule: Tenant scoped unless the selected actor is performing an explicitly documented platform action. The x organization id header or authenticated session context selects the tenant. It does not grant access.
Explicit deny: An applicable explicit deny overrides an allow. Knowing or supplying a resource identifier never grants access.

Address, query and header fields

Field	Location	Presence	Type	Meaning	Limits and example
`x-request-id`	header	Optional	string	Optional caller supplied correlation identifier. Pūnaha returns the effective value in the response header.	Minimum length: 1. Maximum length: 200. Example: example request 001
`runId`	path	Required	string	The run id that identifies the resource selected by this operation.	Minimum length: 1. Example: example runid
`workflowId`	path	Required	string	The workflow id that identifies the resource selected by this operation.	Minimum length: 1. Example: example workflowid

Request body

This operation does not define a request body.

Responses

Status	Meaning and correction boundary	Body
`200`	A Server Sent Event stream that reports waiting or terminal workflow run state. Reconnect and replay behaviour is operation specific.	`text/event-stream`, list of `ServerSentEvent`
`401`	The operation failed with HTTP 401. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`402`	The operation failed with HTTP 402. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`403`	The operation failed with HTTP 403. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`404`	The operation failed with HTTP 404. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`423`	The operation failed with HTTP 423. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`500`	The operation failed with HTTP 500. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`503`	The operation failed with HTTP 503. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`

200 response fields4 documented fields

200 response fields

Field	Presence	Type	Meaning	Empty and default	Limits and example	Access, sensitivity and lifecycle
`data`	required	string	Event payload after Server Sent Event parsing. JSON payloads remain string encoded and are interpreted using contentSchema.	Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present.	Example: {"status":"completed"}	Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release.
`event`	optional	string	Optional event type used to select the event specific payload meaning.	Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present.	Example: workflow run	Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release.
`id`	optional	string	Optional event identifier used for ordering or reconnection when the operation supports replay.	Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present.	Example: example event 001	Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release.
`retry`	optional	integer	Optional server suggested reconnection delay in milliseconds.	Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present.	Minimum: 0. Example: 2000	Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release.

Terminal workflow event

{
  "data": "{\"status\":\"completed\"}",
  "event": "workflow-run",
  "id": "example-event-001"
}

Effects

Behaviour and other effects

Changes: Reads current state and does not intentionally change a Product resource.
Audit events: None
Background work: The operation may create, observe, or advance background work. Use the related read, event, or status operation before retrying after an uncertain outcome.
External effects: No external call is inferred from the route name. Operation specific service behaviour remains authoritative.
Transaction boundary: The HTTP success or error describes the synchronous boundary. Background operations have their own observable lifecycle and may outlive the request.

Operation

Reliability

Idempotent: Yes
Retry: A retry is normally safe only with the same resource, body, tenant, and concurrency preconditions. Confirm the first outcome when external effects are possible.
Concurrency: Use documented If Match or resource revision fields where exposed. Otherwise read current state before changing it and handle HTTP 409 conflicts.
Consistency: The response reflects the synchronous operation boundary. Background and provider backed state can converge later and must be read through its status operation.
Timeout: Client timeouts do not cancel completed or already started server work unless the operation explicitly supports cancellation.
Request ID: Send or record x request id and retain the returned value for diagnosis.

Errors and corrections

Status	Code	Cause	Correction	Retryable	Partial work
`401`	`AUTHENTICATION_REQUIRED`	A valid authenticated session or supported token is required.	Authenticate again using a supported mechanism and confirm that the credential is current.	No unchanged retry	No requested mutation is expected before this failure boundary.
`402`	`FEATURE_NOT_LICENSED`	The active licence does not include a required entitlement.	Use an operation covered by the active entitlement or ask the System Owner to review the signed licence.	No unchanged retry	No requested mutation is expected before this failure boundary.
`403`	`PERMISSION_REQUIRED`	The authenticated actor does not have the exact permission or resource action.	Select the correct tenant and resource, then ask an authorised administrator to grant the exact documented action if appropriate.	No unchanged retry	No requested mutation is expected before this failure boundary.
`404`	`NOT_FOUND`	The selected resource does not exist in the authorised scope.	Obtain the identifier from the related list or create operation and confirm the selected tenant.	No unchanged retry	No requested mutation is expected before this failure boundary.
`423`	`LICENCE_REMEDIATION_REQUIRED`	The installation is restricted and permits only licence remediation actions.	Complete the indicated licence or membership remediation before retrying Product work.	No unchanged retry	No requested mutation is expected before this failure boundary.
`500`	`INTERNAL_ERROR`	Pūnaha could not complete the operation because of an unexpected internal failure.	Retain x request id and the stable error code, avoid blind retries, and investigate the operation or contact support. Code: INTERNAL_ERROR.	No unchanged retry	No requested mutation is expected before this failure boundary.
`500`	`STREAM_UNAVAILABLE`	HTTP streaming is unavailable.	Retain x request id and the stable error code, avoid blind retries, and investigate the operation or contact support. Code: STREAM_UNAVAILABLE.	No unchanged retry	No requested mutation is expected before this failure boundary.
`503`	`DEPENDENCY_UNAVAILABLE`	A required node, database, provider, or service is temporarily unavailable.	Retain x request id, check health and the named dependency, then retry with bounded backoff when safe.	Yes, with the documented safeguards	No requested mutation is expected before this failure boundary.

Code examples

Use a supported credential and synthetic data. Do not disable TLS checks or retry a request that changes state blindly.

cURL example

curl --request GET "$PUNAHA_URL/api/workflows/example-workflowid/runs/example-runid/events/stream" \
  --header "Authorization: Bearer $PUNAHA_TOKEN" \
  --header "x-request-id: example-request-001"

JavaScript example

const response = await fetch(`${PUNAHA_URL}/api/workflows/example-workflowid/runs/example-runid/events/stream`, {
  method: "GET",
  headers: {
  "x-request-id": "example-request-001",
  "Authorization": "Bearer ${PUNAHA_TOKEN}"
}
});

if (!response.ok) throw new Error(`Pūnaha request failed: ${response.status}`);
const result = response.status === 204 ? undefined : await response.json();

C# example

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient { BaseAddress = new Uri(punahaUrl) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", punahaToken);
using var request = new HttpRequestMessage(HttpMethod.Get, "/api/workflows/example-workflowid/runs/example-runid/events/stream");
request.Headers.Add("x-request-id", "example-request-001");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

PowerShell example

$headers = @{ Authorization = "Bearer $env:PUNAHA_TOKEN"; "x-request-id" = "example-request-001" }
Invoke-RestMethod -Method GET `
  -Uri "$env:PUNAHA_URL/api/workflows/example-workflowid/runs/example-runid/events/stream" `
  -Headers $headers

deleteapiWorkflowsWorkflowId, same domain
deleteapiWorkflowsWorkflowIdRunsRunId, same domain
deleteapiWorkflowsWorkflowIdStar, same domain
getapiWorkflows, read or monitor
getapiWorkflowsBpmnConformance, read or monitor
getapiWorkflowsBpmnConformanceReport, read or monitor

Version history

Next Product release: Operation documented from the current registered Go route and handler contract.

Was this page helpful?

Your answer helps us improve the documentation.

Do not include personal information, customer information, passwords, or keys.

Get workflows events (GET /api/workflows/{workflowId}/runs/{runId}/events/stream)

Operation details

Purpose

When to use it

When not to use it

Availability

Access

Address, query and header fields

Request body

Responses

200 response fields

Behaviour and other effects

Reliability

Errors and corrections

Code examples

Version history

Was this page helpful?

Browse documentation

Choose a version

Search the guides

View the full screenshot

Operation details

Purpose

When to use it

When not to use it

Availability

Access

Address, query and header fields

Request body

Responses

200 response fields

Behaviour and other effects

Reliability

Errors and corrections

Code examples

Related APIs

Version history

Was this page helpful?