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

# Get Search Response

> Get a search response by search_id. 



## OpenAPI

````yaml GET /search/{search_id}
openapi: 3.0.0
info:
  title: Cloudglue API
  description: API for Cloudglue
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 0.7.10
servers:
  - url: https://api.cloudglue.dev/v1
security:
  - bearerAuth: []
paths:
  /search/{search_id}:
    get:
      tags:
        - Search
      summary: Get a search response by ID
      description: 'Get a search response by search_id. '
      operationId: getSearchById
      parameters:
        - name: search_id
          in: path
          required: true
          description: The ID of the search response to get
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: A search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Search response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchResponse:
      type: object
      required:
        - id
        - object
        - scope
        - results
        - total
        - limit
      properties:
        id:
          type: string
          format: uuid
          description: ID of the search response
        object:
          type: string
          enum:
            - search
          description: Object type, always 'search'
        query:
          type: string
          description: >-
            The search query that was executed (for text search) or the source
            image URL/base64 indicator (for face search)
        scope:
          type: string
          enum:
            - file
            - segment
            - face
          description: The search scope that was used
        group_by_key:
          type: string
          enum:
            - file
          description: >-
            The key used for grouping results. Only present when group_by_key
            was specified in the request and results are grouped.
        group_count:
          type: integer
          description: >-
            Number of groups in the results. Only present when group_by_key is
            specified.
        search_modalities:
          $ref: '#/components/schemas/SearchModalities'
        results:
          type: array
          description: Array of search results ranked by relevance score
          items:
            oneOf:
              - $ref: '#/components/schemas/FileSearchResult'
              - $ref: '#/components/schemas/SegmentSearchResult'
              - $ref: '#/components/schemas/FaceSearchResult'
              - $ref: '#/components/schemas/SegmentGroupResult'
              - $ref: '#/components/schemas/FaceGroupResult'
        total:
          type: integer
          description: >-
            Total number of results returned. When group_by_key is specified,
            this represents the total number of items across all groups (not the
            number of groups).
        limit:
          type: integer
          description: The limit that was applied to the search
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
    SearchModalities:
      type: array
      items:
        type: string
        enum:
          - general_content
          - speech_lexical
          - ocr_lexical
          - tag_semantic
          - tag_lexical
      maxItems: 5
      description: >
        Specifies the type(s) of search to execute. When multiple modalities are
        specified, a hybrid search is executed that combines results from each
        modality.


        Available modalities:

        - `general_content`: baseline for matching the content of the search
        item (file/segment) based on visual or spoken content similarity to
        provided short natural language query string

        - `speech_lexical`: performs keyword based search (e.g. query of
        `president` matching `president` or `presidential` strings) and exact
        match (e.g. specifically find mentions of `"Barack Obama"` or `"Donald
        Trump"`) against speech content present in search item

        - `ocr_lexical`: performs keyword based search and exact match against
        screen text content present in search item

        - `tag_semantic`: performs basic word semantic similarity search against
        tag values associated with search items (e.g. `query=animal` expected to
        match tags with value containing `dog` or `cat`)

        - `tag_lexical`: performs keyword based search and exact match against
        tag values associated with search items


        Only applicable when search `scope=file` or `scope=segment`.
    FileSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - score
        - id
      properties:
        type:
          type: string
          enum:
            - file
          description: Result type, always 'file'
        file_id:
          type: string
          format: uuid
          description: ID of the file
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        id:
          type: string
          format: uuid
          description: ID of the search document
        score:
          type: number
          description: Relevance score (higher is more relevant)
        filename:
          type: string
          nullable: true
          description: Original filename of the video
        summary:
          type: string
          nullable: true
          description: Generated summary of the video
        generated_title:
          type: string
          nullable: true
          description: Generated title of the video
        thumbnail_url:
          type: string
          format: uri
          description: URL of the thumbnail for the file if available.
        tag:
          $ref: '#/components/schemas/SearchTagResponse'
    SegmentSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - segment_id
        - score
        - id
        - start_time
        - end_time
      properties:
        type:
          type: string
          enum:
            - segment
          description: Result type, always 'segment'
        file_id:
          type: string
          format: uuid
          description: ID of the file
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        segment_id:
          type: string
          format: uuid
          description: ID of the segment
        id:
          type: string
          format: uuid
          description: ID of the search document
        score:
          type: number
          description: Relevance score (higher is more relevant)
        start_time:
          type: number
          description: Start time of the segment in seconds
        end_time:
          type: number
          description: End time of the segment in seconds
        title:
          type: string
          nullable: true
          description: Title associated with the segment
        filename:
          type: string
          nullable: true
          description: Original filename of the video
        visual_description:
          type: array
          description: Visual descriptions for the segment
          items:
            type: object
            properties:
              text:
                type: string
                description: Description of visual content in the segment
              start_time:
                type: number
                description: Start time of the visual content in seconds
              end_time:
                type: number
                description: End time of the visual content in seconds
        scene_text:
          type: array
          description: Text detected on screen in the segment
          items:
            type: object
            properties:
              text:
                type: string
                description: Text detected on screen
              start_time:
                type: number
                description: Start time of the text in seconds
              end_time:
                type: number
                description: End time of the text in seconds
        speech:
          type: array
          description: Speech transcription for the segment
          items:
            type: object
            properties:
              speaker:
                type: string
                description: Identified speaker
              text:
                type: string
                description: Transcribed speech text
              start_time:
                type: number
                description: Start time of speech in seconds
              end_time:
                type: number
                description: End time of speech in seconds
        thumbnail_url:
          type: string
          format: uri
          description: URL of the thumbnail for the segment if available
        tag:
          $ref: '#/components/schemas/SearchTagResponse'
        metadata:
          type: object
          description: User-provided metadata about the segment, if provided.
        keyframes:
          type: array
          description: Keyframes for the segment
          items:
            type: object
            properties:
              time_in_seconds:
                type: number
                description: Time of the keyframe in seconds
              thumbnail_url:
                type: string
                format: uri
                description: URL of the thumbnail for the keyframe
    FaceSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - face_id
        - frame_id
        - score
        - timestamp
      properties:
        type:
          type: string
          enum:
            - face
          description: Result type, always 'face'
        file_id:
          type: string
          format: uuid
          description: ID of the file containing the matched face
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        face_id:
          type: string
          format: uuid
          description: ID of the detected face
        frame_id:
          type: string
          format: uuid
          description: ID of the frame where the face was detected
        score:
          type: number
          description: Similarity score (higher is more similar)
        timestamp:
          type: number
          minimum: 0
          description: Timestamp of the frame in seconds
        face_bounding_box:
          type: object
          required:
            - height
            - width
            - top
            - left
          properties:
            height:
              type: number
              minimum: 0
              maximum: 1
              description: Height of the bounding box (normalized 0-1)
            width:
              type: number
              minimum: 0
              maximum: 1
              description: Width of the bounding box (normalized 0-1)
            top:
              type: number
              minimum: 0
              maximum: 1
              description: Top position of the bounding box (normalized 0-1)
            left:
              type: number
              minimum: 0
              maximum: 1
              description: Left position of the bounding box (normalized 0-1)
        thumbnail_url:
          type: string
          description: URL of the frame thumbnail
    SegmentGroupResult:
      type: object
      required:
        - type
        - matched_items
        - file_id
        - item_count
        - best_score
      properties:
        type:
          type: string
          enum:
            - segment_group
          description: Result type, always 'segment_group'
        matched_items:
          type: array
          items:
            $ref: '#/components/schemas/SegmentSearchResult'
          description: Array of segment search results that belong to this file
        file_id:
          type: string
          format: uuid
          description: ID of the file that this group represents
        item_count:
          type: integer
          description: Number of matched items in this group
        best_score:
          type: number
          description: The highest score among all items in this group
    FaceGroupResult:
      type: object
      required:
        - type
        - matched_items
        - file_id
        - item_count
        - best_score
      properties:
        type:
          type: string
          enum:
            - face_group
          description: Result type, always 'face_group'
        matched_items:
          type: array
          items:
            $ref: '#/components/schemas/FaceSearchResult'
          description: Array of face search results that belong to this file
        file_id:
          type: string
          format: uuid
          description: ID of the file that this group represents
        item_count:
          type: integer
          description: Number of matched items in this group
        best_score:
          type: number
          description: The highest score among all items in this group
    SearchTagResponse:
      type: object
      description: >-
        The associated tag for the search result if it exists. Only provided for
        search requests with tag_semantic or tag_lexical search modalities.
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the tag
        value:
          type: string
          description: The value of the tag
        label:
          type: string
          description: The label of the tag
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````