Management history API

The API can be used to view historical information about Pexip Infinity conference instances that are no longer in progress. For example, this can be used to obtain Call Detail Records (CDRs) of the Pexip Infinity platform.

Note that all date and time fields are in UTC time format.

Up to 10,000 conference instances are retained, along with all the participant instances associated with each of those conferences. Above 10,000 conference instances, each time a new entry is made the oldest entry is deleted (along with all the participant instances associated with it).

For more information and examples about how you can extract history data and view it in tools such as Excel and PowerBI, see Extracting and analyzing call data.

History resources

The following history resources are available via the REST API:

Component Path
Alarm history /api/admin/history/v1/alarm/
Backplane /api/admin/history/v1/backplane/
Backplane media statistics /api/admin/history/v1/backplane/<backplane_id>/media_stream/
Conference instance /api/admin/history/v1/conference/
Participant media statistics /api/admin/history/v1/participant/<participant_id>/media_stream/
Participant /api/admin/history/v1/participant/
Conferencing Node events /api/admin/history/v1/workervm_status_event/

Resource details

More information can be obtained for each resource by downloading the resource schema in a browser. You may want to install a JSON viewer extension to your browser in order to view the JSON strings in a readable format.

For example, to view the schema for backplane instances the URI would be:

https://<manageraddress>/api/admin/history/v1/backplane/schema/?format=json

Each schema contains information on the available fields including:

  • whether the field is optional (nullable: true) or required (nullable: false)
  • the type of data the field must contain
  • the choices for the field, e.g. valid_choices: ["audio", "video", "video-only"]
  • which criteria can be used for filtering and ordering searches
  • help text with additional information on usage.

Resource methods

Each history resource supports the following HTTP methods:

Method Action
GET Retrieves the history for a resource.

Pagination and filtering

History requests can be parameterized with pagination and filter fields. For more information, see Retrieving, paginating, filtering and ordering resource details.

Examples

Getting all conference instances

Retrieving all the conference history is achieved by submitting a GET request to the resource URI for conference history:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/history/v1/conference/",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Conference history:", json.loads(response.text)['objects']

Note that up to 10,000 conference instances may be stored in the history and by default the response is paginated.

Example output

Conference history: [
{
    'duration': 579,
    'end_time': '2015-04-10T09:49:26.556929',
    'id': '8583f400-7886-48c9-874b-5fefc2ac097e',
    'instant_message_count': 0,
    'name': 'meet.alice',
    'participant_count': 3,
    'participants': [
        '/api/admin/history/v1/participant/e9883f1d-88ca-495d-8366-b6eb772dfe57/',
        '/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
        '/api/admin/history/v1/participant/29744376-0436-4fe1-ab80-06d93c71eb1c/'
      ],
    'resource_uri': '/api/admin/history/v1/conference/8583f400-7886-48c9-874b-5fefc2ac097e/',
    'service_type': 'conference',
    'start_time': '2015-04-10T09:39:47',
    'tag': ''
    },				
]

Getting all participants for a conference instance

Retrieving all the participants for a historical conference instance is achieved by submitting a GET request to the resource URI for participant history and supplying a query parameter to specify the conference.

The following example finds all participants for the conference with the ID 00000000-0000-0000-0000-000000000001:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/history/v1/participant/?conference=00000000-0000-0000-0000-000000000001",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Participants for conference:", json.loads(response.text)['objects']

Example output

Participants for conference: [
    {
    'bandwidth': 768,
    'call_direction': 'in',
    'call_quality': '1_good',
    'call_uuid': 'b0a5b554-d1de-11e3-a321-000c29e37602',
    'conference': '/api/admin/history/v1/conference/00000000-0000-0000-0000-000000000001/',
    'conference_name': 'VMR_1',
    'conversation_id': 'b0a5b554-d1de-11e3-a321-000c29e37602',
    'disconnect_reason': 'Call disconnected',
    'display_name': 'Bob',
    'duration': 519,
    'encryption': 'On',
    'end_time': '2015-04-02T09:55:33.141261',
    'has_media': True,
    'id': '00000000-0000-0000-0000-000000000003',
    'is_streaming': false,
    'license_count': 1,
    'license_type': 'port',
    'local_alias': 'meet@example.com',
    'media_node': '10.0.0.1',
    'media_streams': [
        {
          'end_time': '2015-07-22T12:43:33.645043',
          'id': 36,
          'node': '10.0.0.1',
          'participant': '/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
          'rx_bitrate': 29,
          'rx_codec': 'opus',
          'rx_packet_loss': 0.0,
          'rx_packets_lost': 0,
          'rx_packets_received': 28091,
          'rx_resolution': '',
          'start_time': '2015-07-22T12:33:31.909536',
          'stream_id': '0',
          'stream_type': 'audio',
          'tx_bitrate': 2,
          'tx_codec': 'opus',
          'tx_packet_loss': 0.0,
          'tx_packets_lost': 0,
          'tx_packets_sent': 56347,
          'tx_resolution': ''
        },
        {
          'end_time': '2015-07-22T12:43:33.683385',
          'id': 37,
          'node': '10.0.0.1',
          'participant': '/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
          'rx_bitrate': 511,
          'rx_codec': 'VP8',
          'rx_packet_loss': 0.01,
          'rx_packets_lost': 2,
          'rx_packets_received': 37027,
          'rx_resolution': '1280x720',
          'start_time': '2015-07-22T12:33:32.151438',
          'stream_id': '1',
          'stream_type': 'video',
          'tx_bitrate': 511,
          'tx_codec': 'VP8',
          'tx_packet_loss': 0.0,
          'tx_packets_lost': 0,
          'tx_packets_sent': 37335,
          'tx_resolution': '768x448'
        }
      ],
    'parent_id': '29744376-0436-4fe1-ab80-06d93c71eb1c',
    'protocol': 'WebRTC',
    'proxy_node': 'None',
    'remote_address': '10.0.0.2',
    'remote_alias': 'Infinity_Connect_Media_10.0.0.2',
    'remote_port': 11007,
    'resource_uri': '/api/admin/history/v1/participant/00000000-0000-0000-0000-000000000003/',
    'role': 'chair',
    'service_tag': '',
    'service_type': 'conference',
    'signalling_node': '10.0.0.1',
    'start_time': '2015-04-02T09:46:53.712941',
    'system_location': 'London',
    'vendor': 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36'
    },
    {
    'bandwidth': 0,
    'call_direction': 'in',
    'call_quality': '0_unknown',
    'call_uuid': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
    'conference': '/api/admin/history/v1/conference/00000000-0000-0000-0000-000000000001/',
    'conference_name': 'VMR_1',
    'conversation_id': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
    'disconnect_reason': 'Call disconnected',
    'display_name': 'Alice',
    'duration': 578,
    'encryption': 'On',
    'end_time': '2015-04-02T09:55:49.348317',
    'has_media': False,
    'id': '00000000-0000-0000-0000-000000000002',
    'is_streaming': false,
    'license_count': 0,
    'license_type': 'nolicense',
    'local_alias': 'meet@example.com',
    'media_node': '10.0.0.1',
    'media_streams': [],
    'parent_id': '',
    'protocol': 'WebRTC',
    'proxy_node': 'None',
    'remote_address': '10.0.0.2',
    'remote_alias': 'Infinity_Connect_10.0.0.2',
    'remote_port': 54686,
    'resource_uri': '/api/admin/history/v1/participant/00000000-0000-0000-0000-000000000002/',
    'role': 'chair',
    'service_tag': '',
    'service_type': 'conference',
    'signalling_node': '10.0.0.1',
    'start_time': '2015-04-02T09:46:11.116767',
    'system_location': 'London',
    'vendor': 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36'
	}
    ]

Note that:

  • Perceived call quality:

    • call_quality is the most frequently occurring call quality calculation, and is determined as described below.
    • historic_call_quality shows the sequence of call quality calculations over time. For completed calls, the system looks at packet loss and jitter over multiple 20 second time windows throughout the call and calculates the call quality per window. To calculate call quality for a time window, packet loss is assessed first: < 1% packet loss is perceived as Good quality; < 3% is OK; < 10% is Bad; otherwise it is Terrible. Then, if jitter is > 40ms the call quality assessment based on packet loss is adjusted to the next level down (e.g. OK is reduced to Bad). These readings are reported as 0 = Unknown, 1 = Good, 2 = OK, 3 = Bad, 4 = Terrible.
    • bucketed_call_quality is a summary of the call quality calculations. For example, reading [0, 7, 3, 1, 2] from left to right means there were 0 x Unknown, 7 x Good, 3 x OK, 1 x Bad and 2 x Terrible quality calculations.

    Note that historic_call_quality and bucketed_call_quality are not reported in the response to management API requests for all participants for a conference instance (current and historic), but this data is reported when requesting a specific participant.

  • conversation_id is the same as call_uuid except for Skype for Business / Lync calls.
  • parent_id is always ''.

Getting all participants for a time period

The following example uses filters to find all the participants whose call ended on 8 April 2015:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/history/v1/participant/?end_time__gte=2015-04-08T00:00:00&end_time__lt=2015-04-09T00:00:00",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Participants for 8th April :", json.loads(response.text)['objects']

Getting all participants with packet loss

The following example uses a filter to find all the participants with a media stream that had transmit packet loss greater than 0.5%:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/history/v1/participant/?media_streams__tx_packet_loss__gte=0.5",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Participants with high transmit packet loss :", json.loads(response.text)['objects']

The following example uses a filter to find all the participants with a media stream that had receive packet loss greater than 0.5%:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/history/v1/participant/?media_streams__rx_packet_loss__gte=0.5",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Participants with high receive packet loss :", json.loads(response.text)['objects']