Workflow Runs

The /workflows/runs endpoints allows you to manage your Workflows Runs.

Get Run Details

Endpoint: /workflows/runs/<WORKFLOW_ID>/<RUN_ID>

Method: GET

Headers

Path Parameters

Example Request

There is no JSON body with this request.

Example Response

{
  "status": "COMPLETED",
  "started_at": 1678886400,
  "closed_at": 1678886460,
  "execution_duration": 60,
  "run_id": "<RUN_ID>",
  "workflow_id": "<WORKFLOW_ID>",
  "type": "StandardContentIngestion",
  "input": {
    "documentId": "<DOCUMENT_ID>"
  },
  "result": {
    "success": true
  },
  "memo": {},
  "history": [
    {
      "event_id": 1,
      "event_time": 1678886400,
      "event_type": "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED",
      "task_id": "1",
      "attempt": 0
    },
    {
      "event_id": 2,
      "event_time": 1678886410,
      "event_type": "EVENT_TYPE_ACTIVITY_TASK_SCHEDULED",
      "task_id": "2",
      "attempt": 0,
      "activity": {
        "name": "processDocument",
        "id": "1",
        "input": ["<input_data>"],
        "scheduledEventId": "2",
        "startedEventId": "3"
      }
    },
    {
      "event_id": 5,
      "event_time": 1678886460,
      "event_type": "EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED",
      "task_id": "5",
      "attempt": 0,
      "result": ["<result_data>"]
    }
  ],
  "pendingActivities": [],
  "error": null
}

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs/<WORKFLOW_ID>/<RUN_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List Workflow Runs

Endpoint: /workflows/runs

Method: POST

Headers

Input Parameters

Example Request

{
  "document_id": "<DOCUMENT_ID>",
  "event_name": "create",
  "rule_id": "<RULE_ID>"
}

Example Response

{
  "runs": [
    {
      "status": "COMPLETED",
      "started_at": 1678886400,
      "closed_at": 1678886460,
      "execution_duration": 60,
      "run_id": "<RUN_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "type": "StandardContentIngestion",
      "initiated_by": "user:123",
      "interaction_name": "default",
      "vertesia_workflow_type": "StandardContentIngestion",
      "visibility": "project"
    }
  ],
  "next_page_token": "base64EncodedToken",
  "has_more": true
}

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "document_id": "<DOCUMENT_ID>",
  "event_name": "create",
  "rule_id": "<RULE_ID>"
}'

Terminate or Cancel Workflow Run

Endpoint: /workflows/runs/<WORKFLOW_ID>/<RUN_ID>/actions/<ACTION>

Method: POST

Headers

Path Parameters

Input Parameters

Note: cancel requests a graceful shutdown of the workflow execution, allowing Temporal Server to run the workflow's cleanup code before ending. In contrast, terminate forcefully ends the workflow without running cleanup code. Use cancel if you want the workflow to clean up resources gracefully; use terminate for immediate termination.

Example Request

{
  "reason": "User requested cancellation"
}

If no reason is provided, you can send an empty body or omit the body entirely.

Example Response

{
  "message": "Workflow <RUN_ID> cancelled"
}

Code Examples

curl --location --request POST 'https://api.vertesia.io/api/v1/workflows/runs/<WORKFLOW_ID>/<RUN_ID>/actions/cancel' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reason": "User requested cancellation"
}'

Signal Workflow Run

Signals are events that workflows listen to and respond to during their execution. Each workflow defines and listens to its own specific signals, which allow external systems or users to send information to a running workflow. For example, the agent workflow listens to the UserInput signal, which corresponds to a new user input from the user to the agent. Signals enable asynchronous communication with workflows, allowing them to react to external events while maintaining their execution state.

Endpoint: /workflows/runs/<WORKFLOW_ID>/<RUN_ID>/signal/<SIGNAL_NAME>

Method: POST

Headers

Path Parameters

Input Parameters

Example Request

{
  "message": "User response to query",
  "data": {
    "approved": true
  }
}

Example Response

{
  "status": "success",
  "message": "Workflow <RUN_ID> signalled with <SIGNAL_NAME>"
}

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs/<WORKFLOW_ID>/<RUN_ID>/signal/<SIGNAL_NAME>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "message": "User response to query",
  "data": {
    "approved": true
  }
}'

Get Workflow Updates

Workflow updates are messages emitted by workflow runs that client applications can fetch using this endpoint or stream in real-time using the Stream Workflow Updates endpoint. These updates provide visibility into the workflow's progress and status during execution. For example, in the agent workflow case, this endpoint would list all the messages sent by the agent to the user during its execution.

Endpoint: /workflows/runs/<WORKFLOW_ID>/<RUN_ID>/updates

Method: GET

Headers

Path Parameters

Query Parameters

Example Response

{
  "messages": [
    {
      "timestamp": 1678886400000,
      "workflow_run_id": "<RUN_ID>",
      "type": "UPDATE",
      "message": "Processing document",
      "details": {
        "progress": 50
      },
      "workstream_id": "workstream-123"
    }
  ]
}

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs/<WORKFLOW_ID>/<RUN_ID>/updates?since=0' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Stream Workflow Updates

This endpoint provides real-time streaming of workflow updates using Server-Sent Events (SSE). Unlike the Get Workflow Updates endpoint which returns a snapshot of messages, this endpoint maintains an open connection and pushes new updates to the client as they occur. This is ideal for building interactive applications that need to display workflow progress in real-time, such as showing live agent responses or processing status updates.

Endpoint: /workflows/runs/<WORKFLOW_ID>/<RUN_ID>/stream

Method: GET

Headers

Path Parameters

Query Parameters

Response Type: Server-Sent Events (SSE) stream

Note: This endpoint returns a Server-Sent Events stream with real-time updates from the workflow execution. It includes historical updates if since parameter is provided.

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs/<WORKFLOW_ID>/<RUN_ID>/stream?since=0' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Post Workflow Updates

This endpoint is used by workflows themselves to emit updates during their execution. In general, this should not be used by client applications. Client applications should use the Get Workflow Updates or Stream Workflow Updates endpoints to consume updates instead. This endpoint is primarily intended for internal workflow execution logic to publish progress messages and status updates.

Endpoint: /workflows/runs/<RUN_ID>/updates

Method: POST

Headers

Path Parameters

Input Parameters

Example Request

{
  "type": "PROGRESS",
  "message": "Processing document 1 of 10",
  "details": {
    "current": 1,
    "total": 10,
    "percentage": 10
  },
  "workstream_id": "workstream-123"
}

Example Response

{
  "success": true
}

Note: Posted updates are stored in Redis with a 90-day TTL (up to 1000 messages) and published to subscribers via Redis pub/sub for real-time streaming.

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/runs/<RUN_ID>/updates' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "PROGRESS",
  "message": "Processing document 1 of 10",
  "details": {
    "current": 1,
    "total": 10,
    "percentage": 10
  },
  "workstream_id": "workstream-123"
}'

List Conversations

This endpoint returns agent workflow runs, which represent conversations between users and AI agents. It's a specialized version of the List Workflow Runs endpoint that filters specifically for conversation-type workflows. The endpoint automatically applies visibility filtering based on user permissions: regular users can see project-level conversations and their own private conversations, while users with workflow superadmin permissions can see all conversations.

Endpoint: /workflows/conversations

Method: POST

Headers

Description: Lists workflow runs that are conversations, with automatic visibility filtering. Regular users can see project-level conversations and their own private conversations. Users with workflow_superadmin permission can see all conversations.

Input Parameters

Same parameters as List Workflow Runs.

Example Request

{
  "status": "running",
  "page_size": 20
}

Example Response

Same response format as List Workflow Runs, but filtered to only include conversation workflows based on visibility settings.

Code Examples

curl --location 'https://api.vertesia.io/api/v1/workflows/conversations' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "status": "running",
  "page_size": 20
}'