> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get workflow error analytics

> Retrieves error analytics for a specific workflow within a time range. This endpoint provides:
- Aggregated error counts grouped by error code
- Detailed error information including session IDs, timestamps, and descriptions
- Support for filtering by time range to analyze error trends
- Configurable result limits for large error sets



## OpenAPI

````yaml run-api/run-api.yaml get /runs/workflow/{workflow_id}/errors
openapi: 3.1.0
info:
  title: CloudCruise Run API
  version: 0.1.0
  description: >-
    Endpoints for managing workflow executions, user interactions, and
    retrieving execution results.
servers:
  - url: https://api.cloudcruise.com
    description: CloudCruise Platform Production API Server
security:
  - AuthScheme: []
paths:
  /runs/workflow/{workflow_id}/errors:
    get:
      summary: Get workflow error analytics
      description: >-
        Retrieves error analytics for a specific workflow within a time range.
        This endpoint provides:

        - Aggregated error counts grouped by error code

        - Detailed error information including session IDs, timestamps, and
        descriptions

        - Support for filtering by time range to analyze error trends

        - Configurable result limits for large error sets
      operationId: get_workflow_errors
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique identifier for the workflow
        - name: start_timestamp
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Start of the time range (ISO 8601 format)
            example: '2025-10-01T00:00:00Z'
        - name: end_timestamp
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: End of the time range (ISO 8601 format)
            example: '2025-10-29T23:59:59Z'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 1000
            description: Maximum number of errors to retrieve
      responses:
        '200':
          description: Workflow error analytics successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorsResponse'
        '400':
          description: Invalid request parameters
        '404':
          description: Workflow not found
components:
  schemas:
    WorkflowErrorsResponse:
      type: object
      description: Aggregated error analytics for a workflow within a specific time range
      properties:
        workflow_id:
          type: string
          format: uuid
          example: d4e5f6a7-89ab-45cd-ef01-456789012abc
          description: Unique identifier for the workflow
        timeframe:
          type: object
          description: Time range for the error analytics
          properties:
            start:
              type: string
              format: date-time
              example: '2025-10-01T00:00:00Z'
              description: Start of the time range
            end:
              type: string
              format: date-time
              example: '2025-10-29T23:59:59Z'
              description: End of the time range
        total_errors:
          type: integer
          example: 15
          description: Total number of errors in the time range
        error_groups:
          type: object
          description: Errors grouped by error code
          additionalProperties:
            $ref: '#/components/schemas/WorkflowErrorGroup'
          example:
            ELEMENT_NOT_FOUND:
              count: 8
              errors:
                - session_id: e5f6a7b8-9abc-4def-0123-56789abcdef0
                  created_at: '2025-10-29T10:00:00Z'
                  error_code: ELEMENT_NOT_FOUND
                  error_category: RECOVERABLE_ERROR
                  message: Element not found on page
                  error_details: The selector did not match any elements on the page
            NETWORK_TIMEOUT:
              count: 7
              errors:
                - session_id: f6a7b8c9-abcd-4ef0-1234-6789abcdef01
                  created_at: '2025-10-29T11:00:00Z'
                  error_code: NETWORK_TIMEOUT
                  error_category: RECOVERABLE_ERROR
                  message: Request timed out
                  error_details: The network request exceeded the timeout limit
      required:
        - workflow_id
        - timeframe
        - total_errors
        - error_groups
    WorkflowErrorGroup:
      type: object
      description: Group of errors with the same error code
      properties:
        count:
          type: integer
          example: 8
          description: Number of times this error occurred
        errors:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowError'
          description: List of individual error occurrences
      required:
        - count
        - errors
    WorkflowError:
      type: object
      description: Individual error occurrence details
      properties:
        session_id:
          type: string
          format: uuid
          example: e5f6a7b8-9abc-4def-0123-56789abcdef0
          description: Session ID where the error occurred
        created_at:
          type: string
          format: date-time
          example: '2025-10-29T10:00:00Z'
          description: When the error occurred
        error_code:
          type: string
          example: ELEMENT_NOT_FOUND
          description: Standardized error code for categorization
        error_category:
          type: string
          nullable: true
          example: RECOVERABLE_ERROR
          description: |-
            High-level category of the error:
            - RECOVERABLE_ERROR: Error that can be retried or recovered from
            - WORKFLOW_ERROR: Error in workflow configuration or logic
            - IGNORE_ERROR: Error that should be ignored (not critical)
            - CRITICAL_ERROR: Error requiring immediate attention
        message:
          type: string
          example: Element not found on page
          description: Brief error message
        error_details:
          type: string
          nullable: true
          example: The selector did not match any elements on the page
          description: >-
            Detailed error description and analysis (null for IGNORE_ERROR
            category)
      required:
        - session_id
        - created_at
        - error_code
        - message
  securitySchemes:
    AuthScheme:
      type: apiKey
      name: cc-key
      in: header
      description: >-
        API key-based authentication. Provide your CloudCruise API key in the
        cc-key header.

````