Execution History

Endpoints for retrieving and managing flow execution history and statistics.

Execution Retrieval

GET /api/history/executions

Gets all executions across all flows with pagination and filtering.

Query Parameters:

• status: Filter by execution status (PASSED, FAILED, RUNNING, etc.)
• flowId: Filter by flow ID
• deviceId: Filter by device ID
• limit: Maximum executions to return (default: 50)
• offset: Number of executions to skip (default: 0)
• startDate: Filter executions from this date (ISO format)
• endDate: Filter executions until this date (ISO format)
• executionType: Filter by execution type (PARENT, SUBFLOW)
• lite: Return lightweight version without full step details (true/false)

Response:

{
  "success": true,
  "executions": [
    {
      "id": "exec-123",
      "flowId": "flow-456",
      "deviceId": "device-789",
      "status": "PASSED",
      "executionType": "PARENT",
      "startTime": "2024-01-01T12:00:00.000Z",
      "endTime": "2024-01-01T12:00:15.000Z",
      "durationMs": 15000,
      "durationFormatted": "15.00s",
      "stepSummary": {
        "total": 5,
        "passed": 5,
        "failed": 0
      },
      "steps": [
        {
          "id": "step-1",
          "sequenceNumber": 1,
          "action": "launch_app",
          "status": "PASSED",
          "durationMs": 2000
        }
      ],
      "flow": {
        "name": "Login Flow"
      },
      "createdAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 100,
    "hasMore": true
  },
  "filters": {
    "status": "PASSED",
    "flowId": null,
    "deviceId": null,
    "startDate": null,
    "endDate": null,
    "executionType": null,
    "lite": false
  },
  "message": "Executions retrieved successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response Fields:

• executions: Array of execution objects
  • id: Execution identifier
  • flowId: Flow identifier
  • deviceId: Device identifier
  • status: Execution status (PASSED, FAILED, RUNNING, etc.)
  • executionType: Type of execution (PARENT, SUBFLOW)
  • startTime: ISO timestamp when execution started
  • endTime: ISO timestamp when execution ended
  • durationMs: Execution duration in milliseconds
  • durationFormatted: Human-readable duration string
  • stepSummary: Summary of step execution results
  • steps: Array of execution steps (excluded if lite=true)
  • flow: Flow information object
• pagination: Pagination metadata
• filters: Applied filter values
• message: Success message
• timestamp: ISO timestamp of the response

GET /api/history/executions/flows/:flowId

Gets execution history for a specific flow.

Parameters:

• flowId: Flow identifier

Query Parameters:

• status: Filter by execution status
• limit: Maximum executions to return (default: 20)

Response:

{
  "success": true,
  "executions": [
    {
      "id": "exec-123",
      "flowId": "flow-456",
      "status": "PASSED",
      "startTime": "2024-01-01T12:00:00.000Z",
      "endTime": "2024-01-01T12:00:15.000Z",
      "durationMs": 15000,
      "durationFormatted": "15.00s",
      "steps": [],
      "flow": {
        "name": "Login Flow"
      }
    }
  ],
  "count": 1,
  "flowId": "flow-456",
  "message": "Flow executions retrieved successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

GET /api/history/executions/:executionId

Gets detailed execution information by execution ID.

Parameters:

• executionId: Execution identifier

Response:

{
  "success": true,
  "execution": {
    "id": "exec-123",
    "flowId": "flow-456",
    "deviceId": "device-789",
    "status": "PASSED",
    "executionType": "PARENT",
    "startTime": "2024-01-01T12:00:00.000Z",
    "endTime": "2024-01-01T12:00:15.000Z",
    "durationMs": 15000,
    "durationFormatted": "15.00s",
    "stepSummary": {
      "total": 5,
      "passed": 5,
      "failed": 0
    },
    "steps": [
      {
        "id": "step-1",
        "sequenceNumber": 1,
        "action": "launch_app",
        "status": "PASSED",
        "durationMs": 2000,
        "executionData": {},
        "errorMessage": null
      }
    ],
    "executionData": {},
    "errorMessage": null,
    "flow": {
      "name": "Login Flow"
    },
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:15.000Z"
  },
  "message": "Flow execution details retrieved successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Error Response (404):

{
  "success": false,
  "error": "Flow execution not found",
  "code": "EXECUTION_NOT_FOUND",
  "message": "Flow execution with ID exec-123 not found"
}

Execution Statistics

GET /api/history/execution-stats

Gets execution statistics and analytics.

Query Parameters:

• flowId: Filter by flow ID
• deviceId: Filter by device ID
• days: Number of days to look back (default: 30)
• startDate: Start date for statistics (ISO format)
• endDate: End date for statistics (ISO format)
• executionType: Filter by execution type
• status: Filter by execution status

Response:

{
  "success": true,
  "stats": {
    "totalExecutions": 150,
    "statusBreakdown": {
      "PASSED": 120,
      "FAILED": 25,
      "RUNNING": 5
    },
    "averageExecutionTimeMs": 15000,
    "averageExecutionTimeFormatted": "15.00s",
    "successRate": "82.8%",
    "completedCount": 145
  },
  "filters": {
    "flowId": null,
    "deviceId": null,
    "days": 30,
    "startDate": null,
    "endDate": null,
    "executionType": null,
    "status": null
  },
  "message": "Execution statistics retrieved successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response Fields:

• stats: Statistics object
  • totalExecutions: Total number of executions
  • statusBreakdown: Object mapping status to count
  • averageExecutionTimeMs: Average execution time in milliseconds
  • averageExecutionTimeFormatted: Human-readable average duration
  • successRate: Success rate percentage (based on completed executions)
  • completedCount: Number of completed executions (PASSED or FAILED)
• filters: Applied filter values

Execution Deletion

DELETE /api/history/executions/:executionId

Deletes a specific execution by ID.

Parameters:

• executionId: Execution identifier

Response:

{
  "success": true,
  "executionId": "exec-123",
  "message": "Successfully deleted execution exec-123",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Error Response (400):

{
  "success": false,
  "error": "executionId is required",
  "code": "MISSING_EXECUTION_ID",
  "message": "Execution ID is required to delete execution"
}

DELETE /api/history/executions/flows/:flowId

Deletes all execution history for a specific flow.

Parameters:

• flowId: Flow identifier

Response:

{
  "success": true,
  "flowId": "flow-456",
  "deletedCount": 25,
  "message": "Successfully deleted 25 execution records for flow flow-456",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Error Response (400):

{
  "success": false,
  "error": "flowId is required",
  "code": "MISSING_FLOW_ID",
  "message": "Flow ID is required to delete execution history"
}

Usage Examples

Get All Executions with Filters

curl -X GET "http://localhost:3000/api/history/executions?status=PASSED&limit=20&offset=0"

Get Flow Execution History

curl -X GET "http://localhost:3000/api/history/executions/flows/flow-456?limit=10"

Get Execution Details

curl -X GET http://localhost:3000/api/history/executions/exec-123

Get Execution Statistics

curl -X GET "http://localhost:3000/api/history/execution-stats?days=30&flowId=flow-456"

Delete Execution

curl -X DELETE http://localhost:3000/api/history/executions/exec-123

Delete Flow Execution History

curl -X DELETE http://localhost:3000/api/history/executions/flows/flow-456

Integration Notes

• Execution history is automatically created when flows are executed
• Executions include both parent flows and subflow executions
• Statistics are calculated based on completed executions (PASSED or FAILED)
• Deletion operations are permanent and cannot be undone
• Use the lite parameter for faster responses when step details are not needed