​
Runs API

This document outlines the API endpoints for managing individual run instances in PySpur.

​
Get Run

Description: Retrieves detailed information about a specific run, including its status, inputs, outputs, and associated tasks.

URL: /run/{run_id}/

Method: GET

Parameters:

run_id: str  # ID of the run to retrieve

Response Schema:

class RunResponseSchema(BaseModel):
    id: str  # Run ID
    workflow_id: str  # ID of the workflow
    workflow_version_id: Optional[str]  # ID of the workflow version
    workflow_version: Optional[WorkflowVersionResponseSchema]  # Details of the workflow version
    status: RunStatus  # Current status of the run
    start_time: datetime  # When the run started
    end_time: Optional[datetime]  # When the run ended (if completed)
    initial_inputs: Optional[Dict[str, Dict[str, Any]]]  # Initial inputs to the workflow
    outputs: Optional[Dict[str, Dict[str, Any]]]  # Outputs from the workflow
    tasks: List[TaskResponseSchema]  # List of tasks in the run
    parent_run_id: Optional[str]  # ID of the parent run (if applicable)
    run_type: str  # Type of run (e.g., "interactive", "batch")
    output_file_id: Optional[str]  # ID of the output file
    input_dataset_id: Optional[str]  # ID of the input dataset
    message: Optional[str]  # Additional information about the run
    duration: Optional[float]  # Duration of the run in seconds
    percentage_complete: float  # Percentage of tasks completed

​
List All Runs

Description: Lists all runs across all workflows with pagination support, ordered by start time descending. This provides a global view of all workflow executions in the system.

URL: /run/

Method: GET

Query Parameters:

page: int  # Page number (default: 1, min: 1)
page_size: int  # Number of items per page (default: 10, min: 1, max: 100)

Response Schema:

List[RunResponseSchema]  # List of run details

​
Get Run Tasks

Description: Retrieves all tasks associated with a specific run, showing the execution details of each node in the workflow.

URL: /run/{run_id}/tasks/

Method: GET

Parameters:

run_id: str  # ID of the run

Response Schema:

List[TaskResponseSchema]

Where TaskResponseSchema contains:

class TaskResponseSchema(BaseModel):
    id: str  # Task ID
    run_id: str  # ID of the run
    node_id: str  # ID of the node
    node_type: str  # Type of the node
    status: TaskStatus  # Status of the task (PENDING, RUNNING, COMPLETED, FAILED, PAUSED, CANCELED)
    start_time: Optional[datetime]  # When the task started
    end_time: Optional[datetime]  # When the task ended
    inputs: Optional[Dict[str, Any]]  # Inputs to the task
    outputs: Optional[Dict[str, Any]]  # Outputs from the task
    error: Optional[str]  # Error message if the task failed
    is_downstream_of_pause: bool  # Whether this task is downstream of a paused node

​
Delete Run

Description: Permanently deletes a run and all its associated tasks. This operation cannot be undone.

URL: /run/{run_id}/

Method: DELETE

Parameters:

run_id: str  # ID of the run to delete

Response: 204 No Content

​
Get Child Runs

Description: Retrieves all child runs of a parent run, useful for tracking nested workflow executions.

URL: /run/{run_id}/children/

Method: GET

Parameters:

run_id: str  # ID of the parent run

Response Schema:

List[RunResponseSchema]  # List of child run details