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

# Search call results

> Searches historical call results with advanced filtering, full-text search, nested JSON queries,
and aggregations. Supports complex queries including date ranges, status filters, agent filtering,
and custom field searches within call additional data.

## Search Capabilities

* **Date range filtering**: Filter by creation or completion time
* **Status filtering**: Filter by call status (Completed, Failed, etc.)
* **Agent filtering**: Search calls for specific agents
* **Full-text search**: Search across call transcripts and metadata
* **Nested JSON queries**: Query custom fields in call additional data
* **Aggregations**: Get statistics grouped by custom fields
* **Sorting**: Sort by any field with ascending/descending order

## Search Examples

<CodeGroup>
  ```json Basic Search
  {
    "page": 0,
    "size": 20,
    "fromDate": "2024-01-01T00:00:00Z",
    "toDate": "2024-01-31T23:59:59Z",
    "callStatuses": ["Completed", "Failed"],
    "includeAggregations": true
  }
  ```

  ```json Text Search
  {
    "searchText": "connection timeout",
    "size": 50
  }
  ```

  ```json Agent Filtering
  {
    "agentIds": ["agent-123", "agent-456"],
    "endpoint": "sales-webhook",
    "includeAggregations": true
  }
  ```

  ```json Nested JSON Search
  {
    "additionalDataFilters": {
      "result.postCallAnalysis.info.age": { "gt": 36 },
      "result.postCallAnalysis.info.name": "Andrew",
      "result.postCallAnalysis.sentiment": "positive"
    }
  }
  ```

  ```json Complex Search
  {
    "fromDate": "2024-01-01T00:00:00Z",
    "callStatuses": ["Completed"],
    "additionalDataFilters": {
      "result.postCallAnalysis.info.age": { "gte": 25, "lte": 65 }
    },
    "includeAggregations": true,
    "aggregationFields": ["result.postCallAnalysis.info.city", "result.postCallAnalysis.sentiment"],
    "sortField": "completedTime",
    "sortDirection": "Descending",
    "size": 100
  }
  ```
</CodeGroup>

## Use Cases

* **Analytics dashboards**: Aggregate call data by custom metrics
* **Quality assurance**: Search calls by sentiment or specific keywords
* **Compliance tracking**: Filter calls by date range and status
* **Custom reporting**: Query nested JSON fields from post-call analysis


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/callresults/search
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - ApiKey: []
  - OAuth: []
tags:
  - name: ActivityLogs
  - name: Agents
  - name: AgentTestCases
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: Copilot
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/callresults/search:
    post:
      tags:
        - CallResults
      summary: Search call results
      description: >-
        Searches historical call results with advanced filtering, full-text
        search, nested JSON queries,

        and aggregations. Supports complex queries including date ranges, status
        filters, agent filtering,

        and custom field searches within call additional data.
      requestBody:
        description: Search criteria and options
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CallResultSearchRequestDto'
              description: >-
                Search parameters for querying completed call results with
                flexible filtering, pagination, and aggregation options. Enables
                searching call history by various criteria including agent,
                status, date range, and custom data fields for analytics and
                reporting.
          text/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CallResultSearchRequestDto'
              description: >-
                Search parameters for querying completed call results with
                flexible filtering, pagination, and aggregation options. Enables
                searching call history by various criteria including agent,
                status, date range, and custom data fields for analytics and
                reporting.
          application/*+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CallResultSearchRequestDto'
              description: >-
                Search parameters for querying completed call results with
                flexible filtering, pagination, and aggregation options. Enables
                searching call history by various criteria including agent,
                status, date range, and custom data fields for analytics and
                reporting.
      responses:
        '200':
          description: Returns search results successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResultSearchResponseDto'
        '400':
          description: Invalid search parameters or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Access denied to organization resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error occurred during search
components:
  schemas:
    CallResultSearchRequestDto:
      type: object
      properties:
        page:
          type: integer
          description: >-
            Page number for pagination, using 0-based indexing where 0 is the
            first page. Defaults to 0 to return the first page of results.
          format: int32
        size:
          maximum: 100
          minimum: 1
          type: integer
          description: >-
            Number of call results to return per page. Defaults to 20, allowing
            you to balance between fewer requests and manageable response sizes.
          format: int32
        agentIds:
          type: array
          items:
            type: string
          description: >-
            Filter results to calls handled by specific agents. When specified,
            only returns calls from the listed agents. Useful for analyzing
            individual agent performance or filtering to specific use cases.
          nullable: true
        callStatuses:
          type: array
          items:
            $ref: '#/components/schemas/CallStatus'
          description: >-
            Filter results by call completion status. When specified, only
            returns calls with matching statuses (Completed, Failed, Canceled,
            etc.). Useful for analyzing success rates or investigating failed
            calls.
          nullable: true
        fromDate:
          type: string
          description: >-
            Start of date range for filtering call results by completion time.
            Only returns calls completed on or after this timestamp. Combine
            with ToDate for specific time period analysis.
          format: date-time
          nullable: true
        toDate:
          type: string
          description: >-
            End of date range for filtering call results by completion time.
            Only returns calls completed on or before this timestamp. Combine
            with FromDate for specific time period analysis.
          format: date-time
          nullable: true
        searchText:
          type: string
          description: >-
            Free-text search query that searches across multiple call fields
            including transcriptions, additional data, endpoints, and other text
            content. Uses full-text search capabilities for natural language
            queries.
          nullable: true
        callIds:
          type: array
          items:
            type: string
          description: >-
            Filter results to specific call IDs. When specified, only returns
            calls with matching identifiers. Useful for retrieving exact calls
            or investigating specific customer interactions.
          nullable: true
        endpoint:
          type: string
          description: >-
            Filter results by the called endpoint (phone number or SIP address).
            Only returns calls to the specified destination. Useful for
            analyzing calls to specific numbers or SIP endpoints.
          nullable: true
        additionalDataFilters:
          type: object
          additionalProperties: {}
          description: >-
            Filter results by values in the call's additional data fields.
            Allows querying custom business data passed to calls, enabling
            searches like finding all calls with specific customer IDs, order
            numbers, or campaign tags.
          nullable: true
        sortField:
          type: string
          description: >-
            Field name to sort results by. Common values include "completedTime"
            (when the call ended), "createdTime" (when the call was queued),
            "durationSeconds" (call length). Defaults to "completedTime" to show
            most recent calls first when using descending order.
          nullable: true
        sortDirection:
          allOf:
            - $ref: '#/components/schemas/SortDirection'
          description: >-
            Direction to sort results. Use Descending (default) to show newest
            or highest values first, or Ascending to show oldest or lowest
            values first.
        includeAggregations:
          type: boolean
          description: >-
            Whether to include aggregated statistics in the response. When true,
            the response includes counts by status, agent, endpoint, and time
            periods. Useful for dashboards and analytics without requiring
            separate aggregation queries.
        aggregationFields:
          type: array
          items:
            type: string
          description: >-
            Custom fields to aggregate on in addition to standard aggregations.
            Allows creating custom breakdowns of call data by specific
            additional data fields or other call properties.
          nullable: true
      additionalProperties: false
      description: >-
        Search parameters for querying completed call results with flexible
        filtering, pagination, and aggregation options. Enables searching call
        history by various criteria including agent, status, date range, and
        custom data fields for analytics and reporting.
    CallResultSearchResponseDto:
      required:
        - executionTimeMs
        - page
        - results
        - size
        - totalCount
        - totalPages
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CallResultResponseDto'
          description: >-
            Call results in the current page. Each result includes call details,
            status, duration, transcription, recording links, and custom data.
            Results are ordered according to the search request's sort
            parameters.
        totalCount:
          type: integer
          description: >-
            Total number of calls matching the search criteria across all pages.
            Use this to calculate pagination metrics (total pages, progress
            indicators) and understand overall result volume.
          format: int64
        page:
          type: integer
          description: >-
            Current page number using 0-based indexing. Matches the Page
            parameter from the search request.
          format: int32
        size:
          type: integer
          description: >-
            Number of results per page. Matches the Size parameter from the
            search request.
          format: int32
        totalPages:
          type: integer
          description: >-
            Total number of pages available based on TotalCount and Size. Useful
            for building pagination controls and determining if more pages
            exist.
          format: int32
        aggregations:
          allOf:
            - $ref: '#/components/schemas/CallResultAggregationsDto'
          description: >-
            Aggregated statistics about the search results including counts by
            status, agent, endpoint, and time periods. Only present when
            IncludeAggregations was true in the search request. Useful for
            dashboards and analytics without additional queries.
          nullable: true
        executionTimeMs:
          type: integer
          description: >-
            Search execution time in milliseconds. Indicates query performance
            and can help identify slow searches that may benefit from more
            specific filters or indexing optimizations.
          format: int64
      additionalProperties: false
      description: >-
        Search results for completed calls including pagination metadata,
        optional aggregations, and performance metrics. Contains all matching
        call records plus statistics for navigating large result sets and
        analyzing call patterns.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    CallStatus:
      enum:
        - Unknown
        - Created
        - Pending
        - Queued
        - Completed
        - Failed
        - Canceled
        - Running
      type: string
      description: >-
        Current status of a call in its lifecycle. Tracks the call's progress
        from creation through completion or failure.
    SortDirection:
      enum:
        - Ascending
        - Descending
      type: string
      description: >-
        Sort direction for ordering search results. Determines whether results
        are returned in ascending (oldest/lowest first) or descending
        (newest/highest first) order.
    CallResultResponseDto:
      required:
        - agentId
        - callAdditionalData
        - callId
        - callStatus
        - callType
        - completedTime
        - createdTime
        - durationSeconds
        - orgId
      type: object
      properties:
        callId:
          minLength: 1
          type: string
          description: Unique identifier of the call.
        agentId:
          minLength: 1
          type: string
          description: Agent that handled this call.
        orgId:
          minLength: 1
          type: string
          description: Organization that owns this call.
        callAdditionalData:
          type: object
          additionalProperties: {}
          description: >-
            Custom business data that was passed to the call. Contains
            application-specific information like customer IDs, order numbers,
            campaign tags, or any other context provided when the call was
            enqueued.
        callStatus:
          allOf:
            - $ref: '#/components/schemas/CallStatus'
          description: >-
            Final status of the call indicating how it ended. Common values
            include Completed (successfully finished), Failed (error occurred),
            or Canceled (deadline exceeded or manually canceled).
        callType:
          allOf:
            - $ref: '#/components/schemas/CallConnectionType'
          description: >-
            Type of connection used for the call indicating how the conversation
            was conducted (phone, web call, chat, etc.).
        completedTime:
          type: string
          description: Timestamp when the call completed (ended or failed).
          format: date-time
        createdTime:
          type: string
          description: Timestamp when the call was originally created and enqueued.
          format: date-time
        durationSeconds:
          type: number
          description: >-
            Duration of the call in seconds from start to completion. For failed
            calls, this may represent partial duration before failure.
          format: double
        endpoint:
          type: string
          description: Phone number or SIP endpoint that was called.
          nullable: true
        sip:
          description: >-
            SIP protocol details and metadata about the telephony connection.
            Contains technical information about the voice connection, codec
            used, and SIP signaling data.
          nullable: true
        result:
          description: >-
            Structured result data from the call's conversation logic. Contains
            outcomes, decisions, collected information, or any data the agent's
            conversation flow produced during the call.
          nullable: true
        transcription:
          type: array
          items: {}
          description: >-
            Conversation transcription as a list of turn-by-turn utterances.
            Each entry represents what was said during the call, useful for
            quality assurance, sentiment analysis, and conversation review.
          nullable: true
        serverJobId:
          type: string
          description: >-
            Internal server job identifier used for tracking call execution in
            the runtime infrastructure. Useful for debugging and correlating
            with server logs.
          nullable: true
        errorMessage:
          type: string
          description: >-
            Error message if the call failed. Describes what went wrong during
            call execution, useful for troubleshooting and identifying
            systematic issues.
          nullable: true
        inspectorUrl:
          type: string
          description: >-
            URL to the call inspector interface for detailed conversation
            analysis, debugging, and quality review. Provides visualization of
            conversation flow, agent decisions, and execution timeline.
          nullable: true
        recordingUrl:
          type: string
          description: >-
            URL to download or stream the call audio recording. Available when
            recording was enabled for the call.
          nullable: true
        score:
          type: number
          description: >-
            Search relevance score when using text search. Higher scores
            indicate better matches to the search query. Only present when
            SearchText was used in the query, helping prioritize most relevant
            results.
          format: double
          nullable: true
        highlights:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Highlighted snippets from fields matching the search query. Keys are
            field names, values are arrays of text excerpts with search terms
            highlighted. Helps users quickly see why a result matched their
            search without reading full transcripts.
          nullable: true
        startWebhookInfo:
          allOf:
            - $ref: '#/components/schemas/StartWebhookInfoDto'
          description: >-
            Information about the start webhook execution for this call.
            Contains HTTP status code, response body, execution timing, and
            success status. Only present when a start webhook was configured for
            the agent. Useful for debugging calls that were cancelled or
            rejected due to incorrect start webhook replies.
          nullable: true
      additionalProperties: false
      description: >-
        Completed call record with full details including conversation data,
        recordings, and search relevance information. Contains all information
        about a finished call for analysis, quality assurance, and customer
        service review.
    CallResultAggregationsDto:
      type: object
      properties:
        statusCounts:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: >-
            Count of calls grouped by final status. Keys are status names
            (Completed, Failed, Canceled, etc.), values are call counts. Useful
            for calculating success rates, identifying failure patterns, and
            monitoring call completion health.
          nullable: true
        agentCounts:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: >-
            Count of calls grouped by agent. Keys are agent IDs, values are call
            counts. Useful for comparing agent activity levels, distributing
            workload, and identifying high-volume agents.
          nullable: true
        endpointCounts:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: >-
            Count of calls grouped by destination endpoint (phone number or SIP
            address). Keys are endpoints, values are call counts. Useful for
            identifying frequently called numbers, analyzing destination
            patterns, and detecting issues with specific endpoints.
          nullable: true
        dateHistogram:
          type: array
          items:
            $ref: '#/components/schemas/DateHistogramBucketDto'
          description: >-
            Count of calls grouped by time periods showing call volume over
            time. Each bucket represents a time interval with a timestamp and
            call count. Useful for identifying peak periods, trending call
            volumes, and visualizing activity patterns.
          nullable: true
        customAggregations:
          type: object
          additionalProperties: {}
          description: >-
            Custom aggregations on user-specified fields from the
            AggregationFields request parameter. Allows grouping and counting
            calls by custom business data fields or other call properties not
            covered by standard aggregations.
          nullable: true
      additionalProperties: false
      description: >-
        Aggregated statistics about call results providing breakdowns by status,
        agent, endpoint, and time periods. Enables analytics dashboards,
        performance monitoring, and trend analysis without processing individual
        call records.
    CallConnectionType:
      enum:
        - Unknown
        - InboundAudio
        - OutboundAudio
        - WebChat
        - WebCall
        - WebPhone
      type: string
      description: >-
        Type of connection used for the call. Indicates how the conversation was
        initiated and what communication channel was used.
    StartWebhookInfoDto:
      required:
        - triggered
      type: object
      properties:
        triggered:
          type: boolean
          description: Whether a start webhook was configured and triggered for this call.
        statusCode:
          type: integer
          description: HTTP status code returned by the start webhook endpoint.
          format: int32
          nullable: true
        statusText:
          type: string
          description: >-
            HTTP status text (reason phrase) returned by the start webhook
            endpoint.
          nullable: true
        responseBody:
          type: string
          description: >-
            Response body returned by the start webhook endpoint (serialized as
            JSON string).
          nullable: true
        executionTimeMs:
          type: number
          description: >-
            Total execution time of the start webhook call in milliseconds,
            including retries.
          format: double
          nullable: true
        isSuccess:
          type: boolean
          description: >-
            Whether the start webhook call was successful (returned a success
            HTTP status code).
          nullable: true
      additionalProperties: false
      description: >-
        Information about the start webhook execution for a call.

        Captures the HTTP response, timing, and success status of the start
        webhook

        that was triggered when the call began (if configured).
    DateHistogramBucketDto:
      required:
        - count
        - date
      type: object
      properties:
        date:
          type: string
          description: >-
            Start timestamp of this time bucket. Represents the beginning of the
            time interval (hour, day, week, etc.) for which calls are counted.
          format: date-time
        count:
          type: integer
          description: >-
            Number of calls that completed during this time bucket. Use this to
            plot call volume over time, identify busy periods, and track trends.
          format: int64
      additionalProperties: false
      description: >-
        Time period bucket for date histogram aggregations showing call volume
        at a specific time interval. Used for visualizing call trends,
        identifying peak periods, and analyzing activity patterns over time.
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authentication (Bearer {key})
      scheme: Bearer
    OAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.dasha.ai/connect/authorize
          scopes:
            platform_api: Platform API

````