Menu

Expand
Rate this page:

Call Summary Resource

Fetch a Call Summary

The call summary resource provides an overview of metadata and quality metrics for a single call. A completed call summary may take up to a half hour to generate, but a partial summary record will be available within ten minutes of a call ending.

GET https://insights.twilio.com/v1/Voice/{CALL_SID}/Summary
Loading Code Sample...
        
        

        Fetch a Call summary

        Loading Code Sample...
              
              

              Fetch a partial Call summary

              Resource Properties

              A call summary is represented by the following properties:

              Property Description
              account_sid The account SID this call belongs to
              attributes Contains call-flow specific details
              call_sid SID for the call
              call_state Status of the call; completed, failed, etc.
              call_type Describes the call type; client, carrier, sip, trunking
              carrier_edge Contains metrics and properties for the Twilio media gateway of a PSTN call
              client_edge Contains metrics and properties for the Twilio media gateway of a Client call
              connect_duration Duration between when the call was answered and when it ended
              created_time Time the call resource was created. Can be different from start_time in the event of queueing due to CPS.
              duration Duration between when the call was initiated and the call was ended
              end_time Call end time
              from The calling party
              parent_account_sid Parent account SID for calls placed using subaccounts.
              parent_call_sid Parent call SID for calls
              processing_state Represents the summarization state of the resource. While the call is in-progress and as we begin assembling the final summary when the call is completed the processing_state will be partial. We will continue to assemble the summary for approximately 30 minutes, after which the processing_state will be changed to complete. The Summary endpoint can be queried for partial summaries by appending ?ProcessingState=partial to the URI.
              processing_version Increments as updates to the summary are made while processing_state is partial. Allows developers to look at processing version instead of state to potentially close books on a call summary sooner than the 30 minute timeout for processing state; e.g. if your calls always contain 6 processing versions that are completed within 5 minutes, you could conceivably get 25 minutes head start using the data with high confidence.
              answered_by If Answering Machine Detection (AMD) is enabled for a call, the answered_by field would contain the results of AMD for that call. AMD enables you to determine the receiving side of an outgoing call and tailor your call flow accordingly. With AMD, you can determine if a human, answering machine or fax machine has picked up an outbound voice API call.
              properties Contains edge-agnostic call-level details.
              sdk_edge Contains metrics and properties for the SDK sensor library for Client calls.
              sip_edge Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call
              start_time Call start time
              tags Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality.
              to The called party
              trust Contains trusted communications details including Branded Call and verified caller ID
              annotation Programmatically labeled annotations for the call. Developers can update the call summary records with annotation during or after a call. Annotations can be updated as long as the Call Summary record is addressable via the API.
              url The URL of the Voice Insights Summary for this call

              Properties object properties

              Edge-agnostic call-level details.

              Property Description
              pdd_ms Post-dial delay in milliseconds
              last_sip_response_num The numeric value of the last SIP response received for the call
              direction The direction of the call; inbound, outbound-api, outbound-dial, trunking-originating, trunking-terminating
              disconnected_by Direction of the SIP BYE received at Twilio signaling gateway.
              queue_time Estimated time in milliseconds between when a Programmable Voice call is created and when the call actually begins.

              Attributes object properties

              Call-flow specific details.

              Property Description
              conference_participant True/false. Indicates if primary media source was a Twilio conference mixer.

              To/From object properties

              Additional metadata for Voice SDK calls.

              Property Description
              callee Dialed destination
              caller Caller ID of calling party
              carrier Serving carrier of destination
              connection landline, mobile, voip
              country_code Two-letter ISO country code
              country_subdivision Additional location details; e.g. California
              city City name based on lat/long or IP address
              location Lat/long for number prefix
              ip_address Public IP of Client user
              number_prefix E.164 country code + three digits

              SDK object properties

              Additional metadata for Voice SDK calls.

              Property Description
              type Version of Twilio SDK; e.g. twilio-js-sdk. twilio-voice-android
              version Twilio SDK version
              platform WebRTC, android, iOS
              region The Twilio region the device registered to
              selected_region The region specified in the device setup
              edge_location The edge location specified
              browser.name Name of browser for calls placed using JavaScript SDK
              browser.major Major version of browser
              browser.version Full version of browser
              os.name Operating system name as reported to the SDK
              os.version Operating system version as reported to the SDK
              device.arch Processor architecture of machine running the Client app; e.g. amd64
              device.model Mobile SDKs only: model name/number reported to the SDK
              device.type Mobile SDKs only: device type reported to the SDK
              device.vendor Mobile SDKs only: hardware manufacturer reported to the SDK
              engine.name JavaScript SDK only: browser engine as detected by the SDK
              engine.version JavaScript SDK only: browser engine version detected by the SDK

              Edges

              There are four possible edges: carrier_edge, client_edge, sdk_edge, and sip_edge. SIP trunking calls will have both a carrier_edge and a sip_edge. Client calls will have both an sdk_edge and a client_edge.

              carrier_edge represents the connection between Twilio and our immediate carrier partners. The metrics here describe the media stream metadata as it was received from the carrier on the inbound, and as it was delivered to the carrier on the outbound.

              client_edge represents the Twilio media gateway for Client calls. The metrics here describe the media stream metadata as it was received from the Client SDK application on the inbound, and as it was sent to the Client SDK application on the outbound.

              NOTE: Voice Insights for mobile SDKs is supported for versions 3.x and later. Calls placed using 2.x mobile SDKs are not supported and details are provided as-is and may not be reliable indicators of actual performance on the handset or subjective experience on the call.

              sip_edge represents the Twilio media gateway for SIP interface and SIP trunking calls. The metrics here describe what was received from your SIP infrastructure on the inbound, and what was delivered to your SIP infrastructure on the outbound.

              Each edge has two child objects: metrics and properties. metrics will have a container for inbound and outbound media streams.

              Edge Metrics object properties

              Property Description
              codec RTP profile number for the media codec
              codec_name Name of the media codec
              packets_received Count of packets received; inbound container only
              packets_sent Count of packets sent; outbound container only
              packets_lost Count of packets lost
              packets_loss_percentage Percentage of packets lost
              jitter Average and max jitter detected
              latency Twilio internal RTP traversal time from ingress to egress. Average and max latency detected.
              packet_delay_variation Distribution of packets delayed by a certain value; e.g. "d50": 24 indicates that 24 packets were delayed by more than 50 ms.

              Edge Properties object properties

              Property Description
              q850_cause ITU-T Q.850 standard definition of telephony disconnect cause. Not available for all edge types or all calls.
              direction Direction of media flow from the perspective of the edge. Inbound or outbound.
              media_region The Twilio region where media was handled.
              signaling_region The Twilio region where signaling was handled.
              edge_location The Twilio edge location where media was handled.
              twilio_media_ip The IP address for Twilio's media gateway. Not available for carrier_edge.
              twilio_signaling_ip The IP address for Twilio's signaling gateway. Not available for carrier_edge.
              external_media_ip The IP address Twilio received media from. Not available for carrier_edge.
              external_signaling_ip The IP address Twilio received signaling from. Not available for carrier_edge.
              sip_call_id SIP call ID for the call between Twilio & your SIP infrastructure. Present on SIP Interface and trunking calls only.
              user_agent Available for trunking calls only
              selected_region Available for Client calls only.
              region Available for Client calls only.
              disconnected_by Available for Client calls only. Identifies if Twilio.Device.disconnect() was called in the local application or if the call was ended by remote party
              trunk_sid The trunk SID for this call. Present on trunking calls only.

              sdk_edge Metrics object properties

              sdk_edge represents the sensor library in the SDK application itself. The metrics here describe the media stream that was received at the SDK from the Twilio media gateway. Packet loss, jitter, MOS, and RTT are reporting on the inbound stream to the SDK. Audio in/audio out levels can be used to detect one-way audio; no audio in indicates an issue with microphone, potentially muting, hardware issue, or browser loss of context for OS audio APIs.

              Property Description
              mos Mean opinion score; a function of jitter, packet loss, and round-trip time. Scale of 0-5 where anything above 4 is considered acceptable. Average, maximum, and minimum values returned.
              rtt Round-trip time; time in milliseconds for packets sent from Twilio's gateway to arrive at the SDK. NOTE: adaptive jitter buffers and dynamic packet loss concealment algorithms may delay actual play out of RTP beyond the RTT value. Average, maximum, and minimum values returned.
              packets_received Count of packets received; inbound container only
              packets_sent Count of packets sent; outbound container only
              packets_lost Count of packets lost
              packets_loss_percentage Percentage of packets lost
              jitter Average and max jitter detected
              tags Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality
              bytes_received Bytes received at the SDK sensors
              bytes_sent Bytes sent from the SDK
              inbound.audio_out Avg/max level for speaker audio
              inbound.audio_in Avg/max level for microphone audio
              outbound.codec_name Friendly name of the RTP codec for the call set in Twilio.Device();
              outbound.codec RTP profile number of the codec for the call set in Twilio.Device();

              sdk_edge Properties object properties

              Property Description
              direction Direction of the call from the perspective of the SDK.
              settings.dscp Indicates whether DSCP was enabled.
              settings.ice_restart_enabled Indicates if ICE restart was enabled.
              settings.edge Twilio Edge Location that was used for this call
              settings.selected_edges Prioritized list of Edge Locations provided during Twilio.Device.setup();

              sdk_edge Events object properties

              Property Description
              levels Count of events by severity for the call.
              groups Count of events by the event group.
              errors Error code and number of occurrences.
              feedback User feedback gathered from the SDK.

              Trust Properties

              Property Description
              branded_call.branded Boolean. Indicates if branding details were successfully displayed on the destination device.
              branded_call.caller Caller ID provided.
              branded_call.use_case Use case for the call.
              branded_call.branded_channel_sid Branded channel SID.
              branded_call.business_sid Business SID.
              branded_call.brand_sid Brand SID.
              verified_caller.verified Boolean. Indicates if the caller ID provided has been verified; e.g. SHAKEN/STIR A attestation.

              Annotation Properties

              Each call summary can be programatically labeled by the developers to add subjective information pertaining to that call. More details on Call Annotation resource can be found here.

              Property Description
              answered_by Enumerated. Which entity answered the call as determined by Answering Machine Detection (AMD). Use this to provide feedback on AMD accuracy.
              connectivity_issue Enumerated. Indicates if the call was labeled for any connectivity issues.
              quality_issues String[]. Indicates if the call was labeled for user perceived quality issues.
              spam Boolean. Indicates if the call was labeled as a spam call.
              call_score Integer. Indicates the labeled call score for that call.
              comment String. Indicates if any comments were added for the call.
              incident String. Indicates if any associated incident or support tickets were added for the call.

              Consuming the Summary API

              The call summary API is fairly deep. There is a top level object with attributes and properties, and each edge has metrics for both directions of the media stream as well as properties and summarized metrics, so an application trying to access the max jitter value on the outbound stream of a Client call would need to retrieve client_edge.metrics.outbound.jitter.max.

              Not all applications will require that level of detail; simply knowing whether or not jitter was detected on the call will suffice, so just checking the top-level tags will answer that question.

              The edge(s) present will depend on the call type. A Voice SDK call will have an sdk_edge and a client_edge. A SIP trunking call will have a sip_edge and a carrier_edge. A SIP domain or <Dial><Sip> call will have only a sip_edge. A PSTN call will have only a carrier_edge.

              See Understanding Twilio Media Edges for more details.

              Read multiple Call Summary resources

              The Call Summary list API allows results to be filtered by date, to/from information, call state, and other dimensions.

              GET https://insights.twilio.com/v1/Voice/Summaries

              The following query string parameters allow you to filter and limit the list returned to you by the REST API. These parameters are case-sensitive.

              Parameters in REST API format

              Parameter Type PII Description
              Subaccount String Not PII The SID of the subaccount that created the call resource(s) to read. Allows parent accounts to make requests of subaccount resources without needing subaccount authentication key and token.
              To String PII MTL:120 Days The called party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name.
              From String PII MTL:120 Days The calling party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name.
              ToCarrier String Not PII The destination carrier.
              FromCarrier String Not PII The origination carrier.
              ToCountryCode String Not PII The destination country code. Based on phone number in To.
              FromCountryCode String Not PII The source country code. Based on phone number in From.
              Branded Boolean Not PII Indicates whether or not a call was branded using Twilio Branded Calls.
              VerifiedCaller Boolean Not PII Indicates whether or not the caller was verified using SHAKEN/STIR.
              HasTag Boolean Not PII Indicates the presence of one or more Voice Insights Call Tags.
              AbnormalSession Boolean Not PII Indicates the last SIP response was not 200 OK.
              StartTime String Not PII Start time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 4h.
              EndTime String Not PII End time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 0m.
              CallType String Not PII carrier, sip, client, trunking
              CallState String Not PII Final call status
              Direction String Not PII outbound_api, outbound_dial, inbound, trunking_originating, trunking_terminating
              SortBy String Not PII start_time, end_time. Defaults to end_time.
              ProcessingState String Not PII partial, completed, all. Defaults to completed.
              AnsweredBy String Not PII The result of Answering Machine Detection (AMD). Results can be: machine_start, machine_end_beep, machine_end_silence, machine_end_other, human, fax, unknown. Refer to AMD for more details.
              PageSize String Not PII defaults to 25
              PageToken String Not PII
              Loading Code Sample...
                    
                    

                    Read multiple Call Summaries from to/from specific carriers for a data range

                    Loading Code Sample...
                          
                          

                          Read multiple Call Summaries from a subaccount with detected issues

                          Loading Code Sample...
                                
                                

                                Read multiple Call Summaries for outbound calls signed with SHAKEN/STIR

                                Loading Code Sample...
                                      
                                      

                                      Read multiple Call Summaries for SIP calls which did not end in 200 OK

                                      Paging

                                      If you are using the Twilio REST API, the list returned to you includes paging information.

                                      If you plan to request more records than will fit on a single page, you can use the provided nextpageuri rather than incrementing through pages by page number.

                                      Using nextpageuri for paging ensures that your next request will pick up where you left off. This can help keep you from retrieving duplicate data if you are actively making or receiving calls.

                                      All of the Twilio Helper Libraries handle paging automatically. You do not need to explicitly request individual pages when using a Helper Library to fetch lists of resources.

                                      Rate this page:

                                      Need some help?

                                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                      Loading Code Sample...
                                            
                                            
                                            

                                            Thank you for your feedback!

                                            Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                            Sending your feedback...
                                            🎉 Thank you for your feedback!
                                            Something went wrong. Please try again.

                                            Thanks for your feedback!

                                            thanks-feedback-gif