openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Voice SDK Stats API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Voice SDK Stats
  description: Retrieve raw Voice SDK call report stats payloads for WebRTC call troubleshooting.
paths:
  /voice_sdk_call_reports:
    get:
      tags:
      - Voice SDK Stats
      summary: List Voice SDK call reports
      description: Returns paginated raw call report stats JSON payloads stored for the authenticated user. The user is derived from Telnyx authentication, not from request parameters.
      operationId: ListVoiceSdkCallReports
      parameters:
      - $ref: '#/components/parameters/voice-sdk-debug_PageConsolidated'
      - $ref: '#/components/parameters/VoiceSdkCallReportSort'
      responses:
        '200':
          description: Paginated raw call report stats payloads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportListResponse'
              examples:
                reports:
                  summary: Call report list
                  value:
                    data:
                    - call_id: 6d6fb6f1-2b82-4d75-9eb5-3c8e995f1ed1
                      voice_sdk_id: VSDK1Cu-AUDpaCkbs5LKcSUK9jLZFcgqLdg
                      voice_sdk_session_id: 0a52a677-9784-4841-ad31-9596c6e5b970
                      voice_sdk_id_decoded:
                        region: us-central-1
                      user_agent: TelnyxRTC/2.24.0 (iOS 17.5)
                      version: 2.24.0
                      telnyx_session_id: 9a0f6b0e-fb1f-44c9-9b53-7f81442b4c5f
                      telnyx_leg_id: 2d0dd8f1-7d90-4f1f-b8e8-67f9fbdfe2bd
                      stored_at: '2026-05-06T20:00:05Z'
                      summary:
                        callId: 6d6fb6f1-2b82-4d75-9eb5-3c8e995f1ed1
                      stats:
                      - intervalStartUtc: '2026-05-06T20:00:00Z'
                        intervalEndUtc: '2026-05-06T20:00:05Z'
                        audio:
                          inbound:
                            packetsReceived: 1840
                            packetsLost: 0
                            jitterAvg: 0.003
                          outbound:
                            packetsSent: 1837
                            bytesSent: 293920
                        connection:
                          roundTripTimeAvg: 0.041
                          bytesSent: 293920
                          bytesReceived: 312880
                        ice:
                          state: succeeded
                          nominated: true
                          local:
                            candidateType: host
                            protocol: udp
                          remote:
                            candidateType: srflx
                            protocol: udp
                        transport:
                          iceState: connected
                          dtlsState: connected
                          srtpCipher: AES_CM_128_HMAC_SHA1_80
                      logs:
                      - timestamp: '2026-05-06T20:00:00Z'
                        level: debug
                        message: rtcpeer candidate selected
                        context:
                          candidateType: host
                          protocol: udp
                      flushReason:
                        type: call-end
                      segment: 0
                      user_id: 3307ca65-df56-4f15-8ba7-589d584d215b
                      organization_id: 06a3dfbd-4988-4fb1-8d28-9b5d85ca624b
                    meta:
                      total_pages: 1
                      total_results: 1
                      page_number: 1
                      page_size: 20
        '400':
          description: Bad request — invalid pagination or sort parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
        '500':
          description: Unexpected server error while listing reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
  /voice_sdk_call_reports/{call_id}:
    get:
      tags:
      - Voice SDK Stats
      summary: Retrieve Voice SDK call reports by call ID
      description: Returns raw call report stats JSON payloads stored for the authenticated user and `call_id`. The user is derived from Telnyx authentication, not from request parameters.
      operationId: GetVoiceSdkCallReport
      parameters:
      - $ref: '#/components/parameters/CallId'
      responses:
        '200':
          description: Raw call report stats payloads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportsResponse'
              examples:
                reports:
                  summary: Call reports
                  value:
                  - call_id: 6d6fb6f1-2b82-4d75-9eb5-3c8e995f1ed1
                    voice_sdk_id: VSDK1Cu-AUDpaCkbs5LKcSUK9jLZFcgqLdg
                    voice_sdk_session_id: 0a52a677-9784-4841-ad31-9596c6e5b970
                    voice_sdk_id_decoded:
                      region: us-central-1
                    user_agent: TelnyxRTC/2.24.0 (iOS 17.5)
                    version: 2.24.0
                    telnyx_session_id: 9a0f6b0e-fb1f-44c9-9b53-7f81442b4c5f
                    telnyx_leg_id: 2d0dd8f1-7d90-4f1f-b8e8-67f9fbdfe2bd
                    stored_at: '2026-05-06T20:00:05Z'
                    summary:
                      callId: 6d6fb6f1-2b82-4d75-9eb5-3c8e995f1ed1
                    stats:
                    - intervalStartUtc: '2026-05-06T20:00:00Z'
                      intervalEndUtc: '2026-05-06T20:00:05Z'
                      audio:
                        inbound:
                          packetsReceived: 1840
                          packetsLost: 0
                          jitterAvg: 0.003
                        outbound:
                          packetsSent: 1837
                          bytesSent: 293920
                      connection:
                        roundTripTimeAvg: 0.041
                        bytesSent: 293920
                        bytesReceived: 312880
                      ice:
                        state: succeeded
                        nominated: true
                        local:
                          candidateType: host
                          protocol: udp
                        remote:
                          candidateType: srflx
                          protocol: udp
                      transport:
                        iceState: connected
                        dtlsState: connected
                        srtpCipher: AES_CM_128_HMAC_SHA1_80
                    logs:
                    - timestamp: '2026-05-06T20:00:00Z'
                      level: debug
                      message: rtcpeer candidate selected
                      context:
                        candidateType: host
                        protocol: udp
                    flushReason:
                      type: call-end
                    segment: 0
                    user_id: 3307ca65-df56-4f15-8ba7-589d584d215b
                    organization_id: 06a3dfbd-4988-4fb1-8d28-9b5d85ca624b
        '400':
          description: Bad request — invalid path parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
        '404':
          description: No call report was found for the authenticated user and call ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
        '500':
          description: Unexpected server error while looking up the report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSdkCallReportV2ErrorResponse'
components:
  schemas:
    VoiceSdkCallReportStats:
      description: Raw stats payload emitted by the Voice SDK and stored without normalization. The exact shape can vary by SDK platform and version. Live responses commonly return an array of interval snapshots, but object-shaped stats payloads are also allowed for compatibility.
      oneOf:
      - type: array
        description: Raw interval stats snapshots emitted by the Voice SDK.
        items:
          type: object
          additionalProperties: true
          description: Raw stats snapshot. It may include WebRTC RTCStatsReport-style entries and audio, connection, ICE, or transport metrics.
      - type: object
        description: Raw stats object emitted by the Voice SDK.
        properties:
          audio:
            type: object
            additionalProperties: true
            description: Raw audio stats such as inbound/outbound packet, byte, jitter, packet-loss, bitrate, and audio-level metrics.
          connection:
            type: object
            additionalProperties: true
            description: Raw connection stats such as round-trip time, packets, and bytes sent or received.
          ice:
            type: object
            additionalProperties: true
            description: Raw ICE candidate-pair information, including selected pair, local/remote candidates, state, and nomination data when provided by the SDK.
          transport:
            type: object
            additionalProperties: true
            description: Raw transport stats such as ICE state, DTLS state, SRTP cipher, TLS version, and selected-candidate-pair changes.
        additionalProperties: true
    VoiceSdkCallReport:
      type: object
      description: A raw call report stats JSON payload. The schema is intentionally permissive because Voice SDK clients can add fields over time.
      properties:
        call_id:
          type: string
          format: uuid
          description: Unique call identifier.
        call_report_id:
          type: string
          description: User-scoped storage grouping identifier derived from the authenticated user. This is not a unique per-call report identifier and may be shared by multiple calls for the same user.
        user_id:
          type: string
          format: uuid
          description: Authenticated user that owns the call report.
        organization_id:
          type: string
          format: uuid
          description: Organization associated with the stored call report when provided by the Voice SDK reporting path.
        voice_sdk_id:
          type: string
          description: Voice SDK instance identifier.
        voice_sdk_session_id:
          type: string
          description: Voice SDK session correlation identifier used to group stats segments for the same SDK session.
        voice_sdk_id_decoded:
          type: object
          additionalProperties: true
          description: Decoded Voice SDK identifier metadata emitted by voice-sdk-proxy when available.
        user_agent:
          type: string
          description: Voice SDK user agent string reported by the client. This is the preferred SDK/platform/version dimension when present.
        version:
          type: string
          description: Legacy SDK version value when the client reports one separately from the user agent.
        telnyx_session_id:
          type: string
          description: Telnyx RTC session identifier for correlating the report with Voice SDK signaling and media-session logs.
        telnyx_leg_id:
          type: string
          description: Telnyx call leg identifier for correlating the report with call-control, SIP, and media troubleshooting data.
        summary:
          type: object
          additionalProperties: true
          description: High-level call metadata.
        stats:
          $ref: '#/components/schemas/VoiceSdkCallReportStats'
        logs:
          $ref: '#/components/schemas/VoiceSdkCallReportLogs'
        flushReason:
          type: object
          additionalProperties: true
          description: Reason the SDK flushed this stats report segment, for example an intermediate socket-close flush.
        segment:
          type: integer
          description: Zero-based stats segment index when the SDK sends segmented or intermediate reports.
        stored_at:
          type: string
          format: date-time
          description: Time when the call report was stored.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp when present.
      additionalProperties: true
    VoiceSdkCallReportV2Error:
      type: object
      description: Standard Telnyx API v2 error object.
      properties:
        code:
          type: string
          description: Telnyx error code.
          example: '10015'
        title:
          type: string
          description: Short, human-readable error title.
          example: Bad Request
        detail:
          type: string
          description: Human-readable details about the error.
          example: 'Missing required query parameter: call_id.'
        source:
          type: object
          description: Reference to the request field that caused the error.
          properties:
            parameter:
              type: string
              description: Query parameter that caused the error.
              example: call_id
            pointer:
              type: string
              description: JSON pointer to the request body field that caused the error.
          additionalProperties: true
        meta:
          type: object
          description: Additional error metadata.
          additionalProperties: true
          properties:
            url:
              type: string
              format: uri
              description: Link to error documentation.
              example: https://developers.telnyx.com/docs/overview/errors/10015
      required:
      - code
      - title
      - detail
      additionalProperties: true
    VoiceSdkCallReportsResponse:
      type: array
      description: Raw Voice SDK call report stats payloads as stored by voice-sdk-debug.
      items:
        $ref: '#/components/schemas/VoiceSdkCallReport'
    VoiceSdkCallReportLogs:
      description: Raw logs payload emitted by the Voice SDK and stored without normalization. Live responses commonly return an array of log entries, but object-shaped log payloads are also allowed for compatibility.
      oneOf:
      - type: array
        description: Raw log entries emitted by the Voice SDK.
        items:
          $ref: '#/components/schemas/VoiceSdkCallReportLogEntry'
      - type: object
        description: Raw logs object emitted by the Voice SDK when logs are grouped under an entries field.
        properties:
          entries:
            type: array
            description: Raw log entries when the SDK groups logs under an entries field.
            items:
              $ref: '#/components/schemas/VoiceSdkCallReportLogEntry'
        additionalProperties: true
    VoiceSdkCallReportV2ErrorResponse:
      type: object
      description: Standard Telnyx API v2 error response envelope.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/VoiceSdkCallReportV2Error'
      required:
      - errors
      additionalProperties: true
    VoiceSdkCallReportListResponse:
      type: object
      description: Paginated raw Voice SDK call report stats payloads as stored by voice-sdk-debug.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VoiceSdkCallReport'
        meta:
          $ref: '#/components/schemas/voice-sdk-debug_PaginationMeta'
      required:
      - data
      - meta
    voice-sdk-debug_PaginationMeta:
      type: object
      title: Pagination Meta
      properties:
        total_pages:
          type: integer
          example: 1
        total_results:
          type: integer
          example: 1
        page_number:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 20
    VoiceSdkCallReportLogEntry:
      type: object
      description: A raw Voice SDK log entry. Additional SDK-specific fields may be present.
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time when the log entry was emitted.
        level:
          type: string
          description: Log level emitted by the SDK.
          enum:
          - debug
          - info
          - warn
          - error
        message:
          type: string
          description: Log message.
        context:
          type: object
          additionalProperties: true
          description: Raw structured context attached to the log entry.
      additionalProperties: true
  parameters:
    VoiceSdkCallReportSort:
      name: sort
      in: query
      description: Set the order of the results by creation date. `asc` and `created_at` sort oldest reports first; `desc` and `-created_at` sort newest reports first. If not given, results are sorted by creation date in descending order.
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
        - created_at
        - -created_at
        default: desc
        example: -created_at
    CallId:
      name: call_id
      in: path
      required: true
      description: Call identifier used to retrieve reports owned by the authenticated user.
      schema:
        type: string
        format: uuid
    voice-sdk-debug_PageConsolidated:
      name: page
      in: query
      description: Consolidated page parameter (deepObject style).
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          number:
            type: integer
            minimum: 1
            default: 1
            example: 1
          size:
            type: integer
            minimum: 1
            default: 20
            example: 20
            maximum: 100
            description: Number of reports per page. Maximum 100.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt