Skip to content

Workflow Execution


Endpoints

GET       /workflows/:id/workflow_executions

A workflow execution is a record of a workflow run, capturing its status, trigger type, and timing details.

The workflow execution object

What a workflow execution object looks like?

{
  "id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
  "run_status": "SUCCEEDED",
  "workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
  "workflow_name": "File Generator Workflow",
  "trigger": "API",
  "workspace": "main",
  "started_worker_id": "wrkr_Sut4ZTaePs4PkdjDliVWYseGD",
  "ender_worker_id": "wrkr_aVFPQTerHF2JaO0hILbp959v7",
  "ender_worker_execution_id": "wkex_3bNhXpQrLo7TmK2sJfGvWe1cA",
  "created": 1632835285,
  "updated": 1632835286,
  "started": 1632835286,
  "duration": 42.23,
  "real_execution_time": 36.29,
  "total_execution_time": 11.45,
  "resume": [
    ...
  ],
  "version": "v1"
}
Property Description
id string Unique identifier (UID) for the workflow execution.
run_status string The outcome of the workflow execution. It is RUNNING while the workflow runs, then SUCCEEDED or FAILED. CANCELED is reserved and is not written by the server today. Poll this field to determine whether a workflow execution has finished (see Polling for a workflow execution's completion).
workflow_id string The unique identifier of the workflow that was executed.
workflow_name string The name of the workflow that was executed.
trigger string The type of trigger that started the execution. It can be MANUAL, API, SCHEDULER_EVENT or EVENT_DRIVEN.
workspace string The workspace where the execution took place.
started_worker_id string The id of the worker that started the execution.
ender_worker_id string The id of the workflow's Ender worker.
ender_worker_execution_id string The id of the Ender's worker execution. It is null until the Ender finishes. Use it to read the result of the run.
created timestamp Time at which the execution was created. Measured in seconds since the Unix epoch.
updated timestamp Time at which the execution was last updated. Measured in seconds since the Unix epoch.
started timestamp Time at which the execution was started. Measured in seconds since the Unix epoch.
duration number Total wall-clock time in seconds from the start of the execution to the end of the Ender.
real_execution_time number Elapsed time in seconds from the start of the Starter to the end of the Ender.
total_execution_time number Sum of worker execution times in seconds.
resume array The worker executions of the run. Retrieve always includes it. A list includes it only when with_resume=True.
version string Indicates the workflow execution's current version.

Legacy: the response also carries a status field (OK, then COMPLETED). It is deprecated and does not say whether the run succeeded. Ignore it.

List workflow executions

Returns a list of executions for a specific workflow. The executions are returned in sorted order, with the most recent execution appearing first.

To list all executions of a workflow, run the following:

curl https://api.everysk.com/v2/workflows/wrkf_P95OLO61oGM5NwFn3W4iMl7rs/workflow_executions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "workflow_executions": [
    {
      "id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
      "run_status": "SUCCEEDED",
      "workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
      "workflow_name": "File Generator Workflow",
      "trigger": "API",
      "workspace": "main",
      "created": 1632835285,
      "updated": 1632835286,
      "started": 1632835286,
      "duration": 42.23,
      "real_execution_time": 36.29,
      "total_execution_time": 11.45,
      "resume": null
    },
    ...
  ],
  "next_page_token": null
}

HTTP Request

GET /workflows/:id/workflow_executions

HTTP Parameters

Parameter Description
id string REQUIRED A unique identifier (UID) for the workflow.
workflow_execution_id string optional, default is null Retrieve a specific workflow execution by its id.
worker_id string optional, default is null Filter executions that involve a specific worker.
with_resume boolean optional, default is False When True, the execution resume data will be included in the response.
page_size integer optional, default is 10 Set the number of objects that will be listed per page.
page_token string optional, default is null The next_page_token from the previous response. See the pagination guide.

Retrieve a workflow execution

Retrieves the details of a specific workflow execution by supplying the execution's id.

To retrieve a workflow execution, run the following:

curl "https://api.everysk.com/v2/workflows/wrkf_P95OLO61oGM5NwFn3W4iMl7rs/workflow_executions?workflow_execution_id=wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "workflow_execution": {
    "id": "wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe",
    "run_status": "SUCCEEDED",
    "workflow_id": "wrkf_P95OLO61oGM5NwFn3W4iMl7rs",
    "workflow_name": "File Generator Workflow",
    "trigger": "API",
    "workspace": "main",
    "created": 1632835285,
    "updated": 1632835286,
    "started": 1632835286,
    "duration": 42.23,
    "real_execution_time": 36.29,
    "total_execution_time": 11.45,
    "resume": [
      ...
    ]
  }
}

HTTP Request

GET /workflows/:id/workflow_executions

HTTP Parameters

Parameter Description
id string REQUIRED A unique identifier (UID) for the workflow.
workflow_execution_id string REQUIRED A unique identifier (UID) for the workflow execution.

Polling for a workflow execution's completion

Since running a workflow is asynchronous, poll the workflow execution until run_status leaves RUNNING. Then check the outcome, and read the result from the Ender's worker execution.

To poll a workflow execution until it finishes, run the following:

workflow_id="wrkf_P95OLO61oGM5NwFn3W4iMl7rs"
workflow_execution_id="wfex_T1eYymTSIptJ4Hyt1Z6p4uGOe"
workspace="main"
timeout=300
poll_interval=2

run_status="RUNNING"
start=$SECONDS

while [ $((SECONDS - start)) -lt "$timeout" ]; do
  response=$(curl -s "https://api.everysk.com/v2/workflows/$workflow_id/workflow_executions?workflow_execution_id=$workflow_execution_id&workspace=$workspace" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -G)

  run_status=$(echo "$response" | jq -r '.workflow_execution.run_status')

  if [ "$run_status" != "RUNNING" ]; then
    break
  fi

  sleep "$poll_interval"
done

if [ "$run_status" == "RUNNING" ]; then
  echo "Timed out after $timeout seconds."
  exit 1
fi

if [ "$run_status" != "SUCCEEDED" ]; then
  echo "Workflow execution failed with run_status: $run_status"
  exit 1
fi

ender_worker_execution_id=$(echo "$response" | jq -r '.workflow_execution.ender_worker_execution_id')

result=$(curl -s "https://api.everysk.com/v2/workflows/$workflow_id/worker_executions?worker_execution_id=$ender_worker_execution_id&with_result=true&workspace=$workspace" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G)

echo "$result" | jq -r '.worker_execution.result'

This example relies on jq to read fields from the JSON responses. It polls every poll_interval seconds (default 2) until timeout seconds pass (default 300), the same defaults as the everysk-lib helpers run_and_wait and wait_for_completion. Retry the poll request itself only on HTTP 429, 502, 503 or 504; never re-run the workflow because a poll request failed.