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

# Search Runs

> Search semantically for runs



## OpenAPI

````yaml post /v1/runs/search
openapi: 3.1.0
info:
  title: Noxus Backend
  description: >-
    Backend API for the Noxus Platform. More information can be found at
    https://docs.noxus.ai
  version: 1.1.0
servers: []
security: []
paths:
  /v1/runs/search:
    post:
      tags:
        - V1 - Runs
      summary: Search Runs Public
      operationId: search_runs_public
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number
            default: 1
            title: Page
          description: Page number
        - name: size
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Page size
            default: 50
            title: Size
          description: Page size
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_PublicRunWithSearchData_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SearchRunRequest:
      properties:
        query:
          type: string
          title: Query
        similarity_threshold:
          type: number
          title: Similarity Threshold
          default: 0
        limit:
          type: integer
          maximum: 100
          minimum: 1
          title: Limit
          default: 10
        offset:
          type: integer
          title: Offset
          default: 0
        context_size:
          type: integer
          title: Context Size
          default: 30
        max_matches_per_run:
          type: integer
          title: Max Matches Per Run
          default: 5
        exact:
          type: boolean
          title: Exact
          default: true
        search_in:
          anyOf:
            - items:
                type: string
                enum:
                  - input
                  - output
                  - other
                  - run_id
              type: array
            - type: 'null'
          title: Search In
      type: object
      required:
        - query
      title: SearchRunRequest
    Page_PublicRunWithSearchData_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PublicRunWithSearchData'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0
          title: Total
        page:
          type: integer
          minimum: 1
          title: Page
        size:
          type: integer
          minimum: 1
          title: Size
        pages:
          type: integer
          minimum: 0
          title: Pages
      type: object
      required:
        - items
        - total
        - page
        - size
        - pages
      title: Page[PublicRunWithSearchData]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublicRunWithSearchData:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        group_id:
          type: string
          format: uuid
          title: Group Id
        workflow_id:
          type: string
          format: uuid
          title: Workflow Id
        input:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input
        output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output
        node_ids:
          anyOf:
            - items:
                type: string
              type: array
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Node Ids
        single_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Single Node Id
        workflow_version_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workflow Version Id
        status:
          $ref: '#/components/schemas/RunStatus'
        progress:
          type: integer
          title: Progress
          default: 0
        progress_details:
          anyOf:
            - $ref: '#/components/schemas/WorkflowProgress'
            - type: 'null'
        definitions:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Definitions
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Meta
        similarity:
          type: number
          title: Similarity
          default: 0
        matches:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Matches
          default: []
      type: object
      required:
        - id
        - group_id
        - workflow_id
        - status
        - created_at
      title: PublicRunWithSearchData
      description: RunWithSearchData for public API — excludes workflow_definition.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    RunStatus:
      type: string
      enum:
        - queued
        - running
        - failed
        - completed
        - stopped
        - awaiting_human_feedback
      title: RunStatus
    WorkflowProgress:
      properties:
        executed_nodes:
          items:
            type: string
          type: array
          title: Executed Nodes
        running_nodes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Running Nodes
        remaining_nodes:
          items:
            type: string
          type: array
          title: Remaining Nodes
        skipped_nodes:
          items:
            type: string
          type: array
          title: Skipped Nodes
          default: []
        error_handler_nodes:
          items:
            type: string
          type: array
          title: Error Handler Nodes
          default: []
        per_node_progress:
          additionalProperties:
            $ref: '#/components/schemas/NodeProgress'
          type: object
          title: Per Node Progress
        subflow_executions:
          additionalProperties:
            $ref: '#/components/schemas/SubflowExecution'
          type: object
          title: Subflow Executions
          default: {}
        per_edge_progress:
          additionalProperties:
            $ref: '#/components/schemas/EdgeProgress'
          type: object
          title: Per Edge Progress
          default: {}
        run_logs:
          additionalProperties:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
              - type: number
              - type: integer
          type: object
          title: Run Logs
      type: object
      required:
        - executed_nodes
        - remaining_nodes
        - per_node_progress
      title: WorkflowProgress
    NodeProgress:
      properties:
        current_it:
          type: integer
          title: Current It
        total_it:
          type: integer
          title: Total It
        status:
          $ref: '#/components/schemas/NodeStatus'
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        warnings:
          items:
            $ref: '#/components/schemas/SpotWarning'
          type: array
          title: Warnings
      type: object
      required:
        - current_it
        - total_it
        - status
      title: NodeProgress
    SubflowExecution:
      properties:
        node_id:
          type: string
          title: Node Id
        workflow_name:
          type: string
          title: Workflow Name
        workflow_id:
          type: string
          title: Workflow Id
        workflow_definition:
          $ref: '#/components/schemas/WorkflowDefinition'
        raw_definition:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Raw Definition
        total_iterations:
          type: integer
          title: Total Iterations
        iterations:
          additionalProperties:
            $ref: '#/components/schemas/WorkflowProgress'
          type: object
          title: Iterations
          default: {}
      type: object
      required:
        - node_id
        - workflow_name
        - workflow_id
        - workflow_definition
        - total_iterations
      title: SubflowExecution
      description: >-
        Some important notes:

        - This stores metadata needed to display subflow results in the
        frontend.

        - The workflow_definition is shared across all iterations (stored once).

        - Each iteration's progress is stored separately in the iterations dict.


        The raw_definition is stored for resume purposes - when resuming a
        paused

        subflow (e.g., after HITL), we must use the exact same workflow
        definition

        that was used originally, not the potentially-modified current version.
    EdgeProgress:
      properties:
        status:
          $ref: '#/components/schemas/EdgeStatus'
          default: pending
      type: object
      title: EdgeProgress
    NodeStatus:
      type: string
      enum:
        - running
        - errored
        - succeeded
        - skipped
        - payment_required
        - awaiting_human_feedback
      title: NodeStatus
    SpotWarning:
      properties:
        detail:
          type: string
          title: Detail
        identifier:
          $ref: '#/components/schemas/WarningIdentifier'
        node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Node Id
        params:
          additionalProperties: true
          type: object
          title: Params
          default: {}
        markdown:
          anyOf:
            - type: string
            - type: 'null'
          title: Markdown
        snippet:
          anyOf:
            - type: string
            - type: 'null'
          title: Snippet
      type: object
      required:
        - detail
        - identifier
      title: SpotWarning
    WorkflowDefinition:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/NodePreview'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/EdgePreview'
          type: array
          title: Edges
      type: object
      required:
        - nodes
        - edges
      title: WorkflowDefinition
    EdgeStatus:
      type: string
      enum:
        - pending
        - active
        - skipped
        - completed
      title: EdgeStatus
    WarningIdentifier:
      type: string
      enum:
        - general
        - model_fallback
        - model_timeout
        - reading_spreadsheet
        - invalid_search
        - no_results_returned
        - integration_warning
        - failed_scraping
        - invalid_value
        - continue_on_error
        - data_ingestion
        - document_already_exists
        - ingestion_timeout
        - libreoffice_conversion
        - low_confidence
        - guardrail_validation
        - kb_creation
        - kb_empty
        - unsupported_qa_file_type
        - unsupported_file_type
        - no_files_to_add_to_kb
        - no_files_added_to_kb
        - no_google_drive_files
        - no_one_drive_files
        - no_sharepoint_files
        - no_websites_scraped
        - websites_failed_scraping
        - empty_file
        - document_overwrite
        - no_content_provided
        - invalid_folder
        - document_name_too_long
        - retry_warning
      title: WarningIdentifier
    NodePreview:
      properties:
        node_config:
          additionalProperties: true
          type: object
          title: Node Config
        connector_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connector Config
        credential_ids:
          additionalProperties:
            type: string
          type: object
          title: Credential Ids
          default: {}
        subflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subflow Id
        id:
          type: string
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          type: string
          title: Type
        subflow_config:
          anyOf:
            - $ref: '#/components/schemas/SubflowConfig'
            - type: 'null'
        plugin_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Plugin Name
      type: object
      required:
        - node_config
        - id
        - type
      title: NodePreview
    EdgePreview:
      properties:
        from_id:
          $ref: '#/components/schemas/ConnectorAddress'
        to_id:
          $ref: '#/components/schemas/ConnectorAddress'
        id:
          type: string
          title: Id
      type: object
      required:
        - from_id
        - to_id
        - id
      title: EdgePreview
    SubflowConfig:
      properties:
        workflow_id:
          type: string
          title: Workflow Id
        workflow_name:
          type: string
          title: Workflow Name
        workflow_nodes:
          items:
            type: string
          type: array
          title: Workflow Nodes
          default: []
      type: object
      required:
        - workflow_id
        - workflow_name
      title: SubflowConfig
    ConnectorAddress:
      properties:
        connector_name:
          type: string
          title: Connector Name
        node_id:
          type: string
          title: Node Id
        key:
          anyOf:
            - type: string
            - type: 'null'
          title: Key
        optional:
          type: boolean
          title: Optional
          default: false
      type: object
      required:
        - connector_name
        - node_id
      title: ConnectorAddress
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````