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

> Get handoff analytics — Get a comprehensive overview of AI-to-human handoff events for a date range, including reason breakdowns, sentiment analysis, trends, and referenced…

# Get handoff analytics



## OpenAPI

````yaml get /handoff-analytics
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /handoff-analytics:
    get:
      summary: Get handoff analytics
      description: >-
        Get a comprehensive overview of AI-to-human handoff events for a date
        range, including reason breakdowns, sentiment analysis, trends, and
        referenced resources.
      operationId: getHandoffAnalytics
      parameters:
        - schema:
            type: string
          in: query
          name: start_date
          required: false
          description: Start date in ISO 8601 format (defaults to 30 days ago)
        - schema:
            type: string
          in: query
          name: end_date
          required: false
          description: End date in ISO 8601 format (defaults to now)
        - schema:
            type: string
          in: query
          name: instruction_id
          required: false
          description: Filter to only handoffs referencing this instruction ID
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandoffAnalyticsPublicResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    HandoffAnalyticsPublicResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/HandoffAnalyticsPublicResponseDto'
      type: object
      properties:
        summary:
          type: string
        total_handoffs:
          type: number
        total_sessions:
          type: number
        start_date:
          type: string
        end_date:
          type: string
        reasons:
          type: array
          items:
            type: object
            properties:
              reason:
                type: string
                enum:
                  - ai_implied_handoff
                  - based_on_instructions
                  - instructions_not_clear
                  - insufficient_knowledge
                  - insufficient_tools
                  - prohibited_topic
                  - user_requested_human_assistance
              count:
                type: number
              percentage:
                type: number
            required:
              - reason
              - count
              - percentage
            additionalProperties: false
        reason_combinations:
          type: array
          items:
            type: object
            properties:
              reasons:
                type: array
                items:
                  type: string
                  enum:
                    - ai_implied_handoff
                    - based_on_instructions
                    - instructions_not_clear
                    - insufficient_knowledge
                    - insufficient_tools
                    - prohibited_topic
                    - user_requested_human_assistance
              session_count:
                type: number
              percentage:
                type: number
            required:
              - reasons
              - session_count
              - percentage
            additionalProperties: false
        sentiments:
          type: array
          items:
            type: object
            properties:
              sentiment:
                anyOf:
                  - type: string
                  - type: 'null'
              count:
                type: number
              percentage:
                type: number
            required:
              - sentiment
              - count
              - percentage
            additionalProperties: false
        trends:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              count:
                type: number
            required:
              - date
              - count
            additionalProperties: false
        knowledge_references:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ai_profile
                  - instruction
                  - knowledge
                  - prohibited_topic
                  - tool
              id:
                type: string
              count:
                type: number
            required:
              - type
              - id
              - count
            additionalProperties: false
        tool_references:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ai_profile
                  - instruction
                  - knowledge
                  - prohibited_topic
                  - tool
              id:
                type: string
              count:
                type: number
            required:
              - type
              - id
              - count
            additionalProperties: false
        instruction_references:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ai_profile
                  - instruction
                  - knowledge
                  - prohibited_topic
                  - tool
              id:
                type: string
              count:
                type: number
            required:
              - type
              - id
              - count
            additionalProperties: false
        prohibited_topic_references:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ai_profile
                  - instruction
                  - knowledge
                  - prohibited_topic
                  - tool
              id:
                type: string
              count:
                type: number
            required:
              - type
              - id
              - count
            additionalProperties: false
      required:
        - summary
        - total_handoffs
        - total_sessions
        - start_date
        - end_date
        - reasons
        - reason_combinations
        - sentiments
        - trends
        - knowledge_references
        - tool_references
        - instruction_references
        - prohibited_topic_references
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````