Track & manage runs
When a workflow is executed, it creates a workflow run that tracks the execution progress. Each node in the workflow creates a node run that captures its status, logs, and output. The run can also store one markdown summary of its outcome.
Viewing workflow runs
From the Workflows page
- Navigate to the Workflows page
- Click on a workflow to view its details
- The Runs tab shows all executions of that workflow
From entity pages
Workflow runs associated with an entity appear in the entity's activity feed and can be accessed from the entity page.
From a dashboard
Add a workflow runs history widget to the home page or a dashboard page. The widget shows runs of the workflows you select, or of every workflow when you leave the selection empty.
Run structure
A workflow run contains:
| Field | Description |
|---|---|
identifier | Unique run identifier (format: wfr_xxxx) |
status | Current status: IN_PROGRESS, CANCELLING, or COMPLETED |
result | Final result: SUCCESS, FAILED, or CANCELLED (null while in progress) |
nodeRuns | Array of node run objects |
variables | Runtime variables including outputs |
workflow | Object containing identifier and version of the workflow |
createdAt | When the run started |
updatedAt | When the run was last updated |
completedAt | When the run finished (null while in progress) |
createdBy | User or system that triggered the run |
summary | Markdown summary of the run, when one has been set. Included when you fetch a single run, and omitted from the runs list. |
Node run structure
Each node run contains:
| Field | Description |
|---|---|
identifier | Unique node run identifier (format: wfnr_xxxx) |
node | Object containing identifier of the node |
status | Current status: IN_PROGRESS or COMPLETED |
result | Final result: SUCCESS, FAILED, or CANCELLED (null while in progress) |
output | Output data from the node |
links | Array of evaluated URLs attached to this node run |
createdAt | When the node started |
updatedAt | When the node was last updated |
completedAt | When the node finished (null while in progress) |
Updating node runs
External systems can update node run status and add logs using Port's API. This is useful when:
- Using asynchronous webhooks
- Processing Kafka messages
- Running long-running operations
Update node run status
curl -X PATCH "https://api.port.io/v1/workflows/nodes/runs/{node_run_id}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"status": "COMPLETED",
"result": "SUCCESS",
"output": {
"resourceId": "abc123",
"deploymentUrl": "https://my-app.example.com"
}
}'
Request body
| Field | Type | Description |
|---|---|---|
status | string | IN_PROGRESS or COMPLETED |
result | string | Required if status is COMPLETED: SUCCESS, FAILED, or CANCELLED |
output | object | Output data to make available to subsequent nodes |
links | string[] | Optional list of URLs to attach to this node run (max 3). These are merged with any links produced by the node's links templates. |
Attaching links via the API
You can attach URLs to a node run when reporting its result. This is useful when the final URL is only known at execution time (for example, a deployment URL returned by an external system).
curl -X PATCH "https://api.port.io/v1/workflows/nodes/runs/{node_run_id}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"status": "COMPLETED",
"result": "SUCCESS",
"output": {
"deploymentId": "dep-abc123"
},
"links": [
"https://app.example.com/deployments/dep-abc123"
]
}'
Links provided in the API payload are merged with any URLs produced by the node's links templates. The combined list appears in the node details panel on the workflow run page.
Adding logs
Use the dedicated logs endpoint to add log entries to a node run:
curl -X POST "https://api.port.io/v1/workflows/nodes/runs/{node_run_identifier}/logs" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"logs": [
{
"level": "INFO",
"message": "Starting deployment to production"
},
{
"level": "INFO",
"message": "Deployment completed successfully"
}
]
}'
Log entry structure
| Field | Type | Description |
|---|---|---|
level | string | Log level: DEBUG, INFO, WARN, or ERROR |
message | string | The log message |
Log levels: DEBUG, INFO, WARN, ERROR
Adding a summary
A workflow run stores at most one markdown summary, such as what was deployed or why the run failed. Each update replaces the previous summary.
Organization admins can set the summary, as can requests authenticated with an organization machine token. A webhook node that calls the Port API uses that token automatically. Any other caller receives 403.
curl -X PATCH "https://api.port.io/v1/workflows/runs/{run_identifier}" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"summary": "## Deployment\n\nService **checkout** deployed to production."
}'
Replace {run_identifier} with the run id (wfr_xxxx). Replace {token} with an organization admin token, or with an organization machine token.
| Field | Type | Description |
|---|---|---|
summary | string or null | Required. Markdown text that replaces the current summary. |
The body must contain only summary. Port trims leading and trailing whitespace before saving. The trimmed text can be at most 10,000 characters. Pass null or "" to clear the summary.
The summary is returned when you fetch that run with GET /v1/workflows/runs/{run_identifier}. It is omitted from the list of runs. You can set it while the run is in progress and after the run has finished. An unknown run identifier returns 404.
From a webhook node
Call the same endpoint from a webhook node, and put the current run id in the URL with {{ .workflowRun.identifier }}. Omit the Authorization header so Port sends the organization's machine token.
{
"identifier": "set-run-summary",
"title": "Set run summary",
"config": {
"type": "WEBHOOK",
"method": "PATCH",
"url": "https://api.port.io/v1/workflows/runs/{{ .workflowRun.identifier }}",
"body": {
"summary": "## Deployment\n\nService **{{ .outputs.trigger.service }}** deployed to **{{ .outputs.trigger.environment }}**."
}
}
}
Replace trigger with your trigger node's identifier. See workflow run context for other values you can include. Open the summary from the workflow run page.
Run outputs
Node outputs are stored in the workflow run's variables.outputs and can be referenced by subsequent nodes.
For webhook nodes (without custom variables), the output includes the full response:
{
"outputs": {
"create_resource": {
"response": {
"data": {
"resourceId": "abc123",
"resourceUrl": "https://..."
}
}
}
}
}
Reference in subsequent nodes:
{
"body": {
"resourceId": "{{ .outputs.create_resource.response.data.resourceId }}"
}
}
If you define custom variables on a node, only those variables are stored as outputs (see Data flow).
Configure visibility for action runs
By default, all organization members can view workflow runs. You can restrict this access using the allowAnyoneToViewRuns property in the workflow definition:
- When enabled (default): All organization members can view the workflow's runs.
- When disabled: Admins can view all runs, while members can only view the runs they executed.
This ensures that sensitive operational data remains accessible only to authorized users while maintaining transparency where appropriate.
Example workflow definition with restricted visibility:
{
"identifier": "my_workflow",
"allowAnyoneToViewRuns": false,
// ...
}
Example
External processing
Here's an example of how an external system might process a webhook from a workflow and report back to Port. This assumes the workflow's webhook node includes the node run identifier in its request body using {{ .workflowNodeRun.identifier }}:
Python example (click to expand)
import requests
def process_webhook(webhook_data):
"""Process a webhook and report back to Port"""
# The node_run_id should be passed explicitly in the webhook body
# by the workflow using {{ .workflowNodeRun.identifier }}
node_run_id = webhook_data['nodeRunId']
# Log the start
add_node_run_logs(node_run_id, [{
"level": "INFO",
"message": "Processing started"
}])
try:
# Do the actual work
result = perform_operation(webhook_data['payload'])
# Log success
add_node_run_logs(node_run_id, [{
"level": "INFO",
"message": f"Operation completed: {result}"
}])
# Report success
update_node_run(node_run_id, {
"status": "COMPLETED",
"result": "SUCCESS",
"output": result
})
except Exception as e:
# Log and report failure
add_node_run_logs(node_run_id, [{
"level": "ERROR",
"message": f"Operation failed: {str(e)}"
}])
update_node_run(node_run_id, {
"status": "COMPLETED",
"result": "FAILED"
})
def add_node_run_logs(node_run_id, logs):
"""Add logs to a node run via Port API"""
response = requests.post(
f"https://api.port.io/v1/workflows/nodes/runs/{node_run_id}/logs",
headers={
"Authorization": f"Bearer {get_port_token()}",
"Content-Type": "application/json"
},
json={"logs": logs}
)
response.raise_for_status()
def update_node_run(node_run_id, data):
"""Update a node run via Port API"""
response = requests.patch(
f"https://api.port.io/v1/workflows/nodes/runs/{node_run_id}",
headers={
"Authorization": f"Bearer {get_port_token()}",
"Content-Type": "application/json"
},
json=data
)
response.raise_for_status()
Cancelling a workflow run
You can cancel a workflow run that is currently in progress. Two modes are available:
| Mode | Behavior | Final status |
|---|---|---|
| Graceful cancel | Waits for any currently executing nodes to finish, then stops the run. | CANCELLED |
| Force cancel | Immediately marks all in-progress nodes as failed and stops the run. May result in incomplete or inconsistent data. | FAILED |
While a graceful cancel is in progress, the run status changes to CANCELLING. The UI polls for updates every 5 seconds during this state.
Who can cancel
Workflow runs can be cancelled by:
- Admins - can cancel any run.
- Run creators - can cancel runs they triggered.
Runs that have already completed cannot be cancelled.
Cancel from the UI
- Open the workflow run page.
- Click the Cancel run button (abort icon) in the header panel.
- A confirmation dialog appears. Click Cancel run to perform a graceful cancel.
If the run is already in CANCELLING state, clicking the button again triggers a force cancel instead.
Limitations
The following run features are not yet available in workflows:
- Re-run workflow: Ability to re-run a workflow from the UI.
- Partial re-run: Re-run from a specific node.