Runs API

The Runs API allows you to execute, monitor, and manage individual workflow runs on the Lumea platform.

Overview

Workflow runs are instances of workflows that are executed with specific input parameters. This API enables you to start new workflow runs, monitor their status, retrieve logs, and manage execution.

Note: Each customer receives a custom deployment with a unique API endpoint. The endpoints described in this documentation should be prefixed with your organization's specific API URL provided during onboarding.

Data Models

WorkflowRun Object

Field	Type	Description
id	string	Unique identifier for the workflow run
workflow_id	string	ID of the workflow being executed
status	string	Current status of the run (pending, running, completed, failed, stopped)
inputs	object	Input parameters provided for this workflow run
queue_id	string	Optional queue ID if run was added to a queue
created_at	string	Timestamp when the run was created
updated_at	string	Timestamp when the run was last updated
state	object	Current internal state of the workflow run (included only when requested)

Endpoints

Start Workflow Run

Initiates a new workflow run, either immediately or by adding it to a queue.

URL: /runs

Method: POST

Request Body:

{
  "workflow_id": "workflow123",
  "worker_task_type": "short_running",
  "inputs": {
    "parameter1": "value1",
    "parameter2": 100
  },
  "queue_id": "queue123"
}

Field	Type	Required	Description
workflow_id	string	Yes	ID of the workflow to execute
worker_task_type	string	No	Type of worker to use (defaults to "short_running")
inputs	object	No	Input parameters for the workflow
queue_id	string	No	Queue ID to add the run to (for deferred execution)

Success Response:

• Code: 200 OK
• Content:

{
  "id": "run123",
  "workflow_id": "workflow123",
  "status": "pending",
  "inputs": {
    "parameter1": "value1",
    "parameter2": 100
  },
  "queue_id": "queue123",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}

Get Workflow Run

Retrieves details of a specific workflow run.

URL: /runs/{run_id}

Method: GET

URL Parameters:

Parameter	Description
run_id	The unique ID of the workflow run

Query Parameters:

Parameter	Required	Description
include	No	Comma-separated list of fields to include (e.g., "state")

Success Response:

• Code: 200 OK
• Content:

{
  "id": "run123",
  "workflow_id": "workflow123",
  "status": "running",
  "inputs": {
    "parameter1": "value1",
    "parameter2": 100
  },
  "queue_id": null,
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:01:00Z"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Stop Workflow Run

Stops a running workflow execution.

URL: /runs/{run_id}/stop

Method: POST

URL Parameters:

Parameter	Description
run_id	The unique ID of the workflow run

Success Response:

• Code: 200 OK
• Content:

{
  "message": "Run stopped successfully"
}

Error Responses:

• Code: 400 Bad Request
  • Content: {"detail": "Run not found"}
  • Content: {"detail": "Error message"}

List Workflow Runs

Retrieves a list of workflow runs with optional filtering.

URL: /runs

Method: GET

Query Parameters:

Parameter	Required	Description
status	No	Filter runs by status
workflow_id	No	Filter runs by workflow ID
queue_id	No	Filter runs by queue ID
limit	No	Maximum number of runs to return
offset	No	Number of runs to skip for pagination
include	No	Comma-separated list of fields to include (e.g., "state")

Success Response:

• Code: 200 OK
• Content:

[
  {
    "id": "run123",
    "workflow_id": "workflow123",
    "status": "completed",
    "inputs": {
      "parameter1": "value1",
      "parameter2": 100
    },
    "queue_id": null,
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:05:00Z"
  },
  {
    "id": "run456",
    "workflow_id": "workflow456",
    "status": "pending",
    "inputs": {
      "parameter1": "value2",
      "parameter2": 200
    },
    "queue_id": "queue123",
    "created_at": "2023-06-01T12:10:00Z",
    "updated_at": "2023-06-01T12:10:00Z"
  }
]

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}

Get Workflow Run Logs

Retrieves logs for a specific workflow run.

URL: /runs/{run_id}/logs

Method: GET

URL Parameters:

Parameter	Description
run_id	The unique ID of the workflow run

Query Parameters:

Parameter	Required	Description
level	No	Filter logs by level (e.g., "info", "error")
after_id	No	Return only logs after the specified log ID

Success Response:

• Code: 200 OK
• Content:

[
  {
    "id": "log123",
    "run_id": "run123",
    "level": "info",
    "message": "Workflow execution started",
    "timestamp": "2023-06-01T12:00:10Z"
  },
  {
    "id": "log124",
    "run_id": "run123",
    "level": "info",
    "message": "Processing input data",
    "timestamp": "2023-06-01T12:00:15Z"
  }
]

Error Responses:

• Code: 400 Bad Request
  • Content: {"detail": "Error message"}
• Code: 404 Not Found
  • Content: {"detail": "Log item not found"}