openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Session Analysis API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Analyze voice AI sessions, costs, and event hierarchies across Telnyx products.
  name: Session Analysis
paths:
  /session_analysis/metadata:
    get:
      description: Returns all available record types and supported query parameters for session analysis.
      operationId: GetSessionAnalysisMetadata
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataOverviewResponse'
          description: Metadata overview
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Internal server error
      summary: Get metadata overview
      tags:
      - Session Analysis
      x-latency-category: responsive
  /session_analysis/metadata/{record_type}:
    get:
      description: Returns detailed metadata for a specific record type, including relationships and examples.
      operationId: GetSessionAnalysisRecordTypeMetadata
      parameters:
      - description: The record type identifier (e.g. "call-control").
        in: path
        name: record_type
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordTypeMetadataResponse'
          description: Record type metadata
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Record type not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Internal server error
      summary: Get record type metadata
      tags:
      - Session Analysis
      x-latency-category: responsive
  /session_analysis/{record_type}/{event_id}:
    get:
      description: Retrieves a full session analysis tree for a given event, including costs, child events, and product linkages.
      operationId: GetSessionAnalysis
      parameters:
      - description: The record type identifier.
        in: path
        name: record_type
        required: true
        schema:
          type: string
      - description: The event identifier (UUID).
        in: path
        name: event_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Whether to include child events in the response.
        in: query
        name: include_children
        required: false
        schema:
          default: true
          type: boolean
      - description: Maximum traversal depth for the event tree.
        in: query
        name: max_depth
        required: false
        schema:
          default: 2
          maximum: 5
          minimum: 1
          type: integer
      - description: Controls what data to expand on each event node.
        in: query
        name: expand
        required: false
        schema:
          default: record
          enum:
          - record
          - none
          type: string
      - description: ISO 8601 timestamp or date to narrow index selection for faster lookups. Accepts full datetime (e.g., 2026-03-17T10:00:00Z) or date-only format (e.g., 2026-03-17).
        in: query
        name: date_time
        required: false
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                cost:
                  currency: USD
                  total: '0.056800'
                meta:
                  event_count: 3
                  products:
                  - ai-voice-assistant
                  - callcontrol-cdrs
                  - inference
                root:
                  children: []
                  cost:
                    cumulative_cost: '0.056800'
                    currency: USD
                    event_cost: '0.001800'
                  event_name: callcontrol-cdrs
                  id: call-123
                  links:
                    records: /v2/detail_records?record_type=callcontrol-cdrs&id=call-123
                    self: /v2/session_analysis/callcontrol-cdrs/call-123
                  product: callcontrol-cdrs
                  record: {}
                  relationship: null
                session_id: call-123
              schema:
                $ref: '#/components/schemas/SessionAnalysisResponse'
          description: Session analysis result
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Invalid request parameters
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Event not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisErrorResponse'
          description: Internal server error
      summary: Get session analysis
      tags:
      - Session Analysis
      x-latency-category: responsive
components:
  schemas:
    EventNode:
      properties:
        children:
          description: Child events in the session tree.
          items:
            $ref: '#/components/schemas/EventNode'
          type: array
        cost:
          $ref: '#/components/schemas/CostInfo'
        event_name:
          description: Name of the event type.
          type: string
        id:
          description: Event identifier.
          type: string
        links:
          $ref: '#/components/schemas/Links'
        product:
          description: Product that generated this event.
          type: string
        record:
          additionalProperties: true
          description: The underlying detail record data. Contents vary by record type.
          type: object
        relationship:
          description: Relationship to the parent node, null for root.
          oneOf:
          - $ref: '#/components/schemas/RelationshipInfo'
          - type: 'null'
      required:
      - id
      - product
      - event_name
      - cost
      - links
      - record
      - children
      type: object
    ChildRelationshipInfo:
      properties:
        child_event:
          type: string
        child_product:
          type: string
        child_record_type:
          type: string
        cost_rollup:
          type: boolean
        description:
          type: string
        relationship_type:
          type: string
        traversal_enabled:
          type: boolean
        via:
          $ref: '#/components/schemas/MetadataFieldMapping'
      required:
      - relationship_type
      - via
      - cost_rollup
      - traversal_enabled
      - description
      - child_product
      - child_event
      - child_record_type
      type: object
    ResponseMeta:
      properties:
        event_count:
          description: Total number of events in the session tree.
          type: integer
        products:
          description: List of distinct products involved in the session.
          items:
            type: string
          type: array
      required:
      - event_count
      - products
      type: object
    QueryParameterInfo:
      properties:
        default:
          type: string
        description:
          type: string
        enum_values:
          items:
            type: string
          type:
          - array
          - 'null'
        max:
          type:
          - integer
          - 'null'
        min:
          type:
          - integer
          - 'null'
        type:
          type: string
      required:
      - type
      - default
      - description
      type: object
    MetadataInfo:
      properties:
        last_updated:
          format: date-time
          type: string
        total_record_types:
          type: integer
      required:
      - total_record_types
      - last_updated
      type: object
    MetadataFieldMapping:
      properties:
        local_field:
          type: string
        parent_field:
          type: string
      required:
      - local_field
      - parent_field
      type: object
    RelationshipInfo:
      properties:
        parent_id:
          description: Identifier of the parent event.
          type: string
        type:
          description: Relationship type identifier.
          type: string
        via:
          $ref: '#/components/schemas/FieldMapping'
      required:
      - type
      - via
      - parent_id
      type: object
    CostSummary:
      properties:
        currency:
          description: ISO 4217 currency code.
          type: string
        total:
          description: Total session cost as a decimal string.
          type: string
      required:
      - total
      - currency
      type: object
    MetadataOverviewResponse:
      properties:
        meta:
          $ref: '#/components/schemas/MetadataInfo'
        query_parameters:
          additionalProperties:
            $ref: '#/components/schemas/QueryParameterInfo'
          description: Map of supported query parameter names to their definitions.
          type: object
        record_types:
          items:
            $ref: '#/components/schemas/RecordTypeInfo'
          type: array
      required:
      - record_types
      - query_parameters
      - meta
      type: object
    Links:
      properties:
        records:
          description: Link to the underlying detail records.
          type: string
        self:
          description: Link to this session analysis node.
          type: string
      required:
      - self
      - records
      type: object
    SessionAnalysisErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/SessionAnalysisError'
          type: array
      required:
      - errors
      type: object
    SessionAnalysisResponse:
      properties:
        cost:
          $ref: '#/components/schemas/CostSummary'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        root:
          $ref: '#/components/schemas/EventNode'
        session_id:
          description: Identifier for the analyzed session.
          type: string
      required:
      - session_id
      - cost
      - root
      - meta
      type: object
    RecordTypeInfo:
      properties:
        aliases:
          items:
            type: string
          type: array
        child_relationships:
          items:
            $ref: '#/components/schemas/ChildRelationshipInfo'
          type: array
        description:
          type: string
        event:
          type: string
        parent_relationships:
          items:
            $ref: '#/components/schemas/ParentRelationshipInfo'
          type: array
        product:
          type: string
        record_type:
          type: string
      required:
      - record_type
      - aliases
      - product
      - event
      - description
      - child_relationships
      - parent_relationships
      type: object
    FieldMapping:
      properties:
        local_field:
          description: Field name on the child record.
          type: string
        parent_field:
          description: Field name on the parent record.
          type: string
      required:
      - local_field
      - parent_field
      type: object
    ParentRelationshipInfo:
      properties:
        cost_rollup:
          type: boolean
        description:
          type: string
        parent_event:
          type: string
        parent_product:
          type: string
        parent_record_type:
          type: string
        relationship_type:
          type: string
        traversal_enabled:
          type: boolean
        via:
          $ref: '#/components/schemas/MetadataFieldMapping'
      required:
      - relationship_type
      - via
      - cost_rollup
      - traversal_enabled
      - description
      - parent_product
      - parent_event
      - parent_record_type
      type: object
    RelationshipMetadata:
      properties:
        max_recommended_depth:
          type: integer
        total_children:
          type: integer
        total_parents:
          type: integer
        total_siblings:
          type: integer
      required:
      - total_children
      - total_siblings
      - total_parents
      - max_recommended_depth
      type: object
    RecordTypeMetadataResponse:
      properties:
        aliases:
          items:
            type: string
          type: array
        child_relationships:
          items:
            $ref: '#/components/schemas/ChildRelationshipInfo'
          type: array
        event:
          type: string
        examples:
          additionalProperties: true
          description: Example queries and responses for this record type.
          type: object
        meta:
          $ref: '#/components/schemas/RelationshipMetadata'
        parent_relationships:
          items:
            $ref: '#/components/schemas/ParentRelationshipInfo'
          type: array
        product:
          type: string
        record_type:
          type: string
      required:
      - record_type
      - aliases
      - product
      - event
      - child_relationships
      - parent_relationships
      - examples
      - meta
      type: object
    SessionAnalysisError:
      properties:
        code:
          type: string
        detail:
          type: string
        message:
          type: string
      required:
      - code
      - message
      type: object
    CostInfo:
      properties:
        cumulative_cost:
          description: Cumulative cost including all descendants.
          type: string
        currency:
          description: ISO 4217 currency code.
          type: string
        event_cost:
          description: Cost of this individual event.
          type: string
      required:
      - event_cost
      - cumulative_cost
      - currency
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http