Management status API

The current status of the Pexip Infinity platform and any conference instances currently in progress can be viewed using the API.

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

Status resources

The following status resources are available via the REST API:

Component Path
Conference instances /api/admin/status/v1/conference/
Conference instances per node /api/admin/status/v1/conference_shard/
Participants /api/admin/status/v1/participant/
Registered aliases /api/admin/status/v1/registration_alias/
Conferencing Nodes /api/admin/status/v1/worker_vm/
Participant media statistics /api/admin/status/v1/participant/<participant_id>/media_stream/
Conferencing Node load statistics /api/admin/status/v1/worker_vm/<worker_vm_id>/statistics/
System locations /api/admin/status/v1/system_location/
System location load statistics /api/admin/status/v1/system_location/<system_location_id>/statistics/
Backplanes /api/admin/status/v1/backplane/
Backplane media statistics /api/admin/status/v1/backplane/<id>/media_stream/
Alarms /api/admin/status/v1/alarm/
Licenses /api/admin/status/v1/licensing/
Conference synchronization /api/admin/status/v1/conference_sync/
List all cloud overflow Conferencing Nodes /api/admin/status/v1/cloud_node/
List all locations monitored for dynamic bursting /api/admin/status/v1/cloud_monitored_location/
List all locations that contain Conferencing Nodes that may be used for dynamic bursting /api/admin/status/v1/cloud_overflow_location/
Exchange scheduler /api/admin/status/v1/exchange_scheduler/

Specifying the object ID in the path

To retrieve the status of a specific resource, append the object ID of the resource to the path.

For example, a path of api/admin/status/v1/conference/68aef1a9-7b1b-4442-848d-cbad4b48b320/ retrieves the status of the conference with a conference ID of 68aef1a9-7b1b-4442-848d-cbad4b48b320.

You must also use the relevant object ID in the path of component requests when retrieving resources such as participant media statistics, Conferencing Node load statistics or backplane media statistics.

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 conference instances the URI would be:

https://<manageraddress>/api/admin/status/v1/conference/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 status resource supports the following HTTP methods:

Method Action
GET Retrieves the current status for a resource.

Pagination and filtering

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

Examples

Getting all active conference instances

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

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

Example output

Active conferences: [
  {
    'start_time': '2015-04-02T09:46:06.106482',
    'resource_uri': '/api/admin/status/v1/conference/00000000-0000-0000-0000-000000000001/',
    'id': '00000000-0000-0000-0000-000000000001',
    'name': 'VMR_1',
    'service_type': 'conference',
    'is_locked': False,
    'is_started': True,
    'guests_muted': False,
    'tag': ''				
  }
]

Getting all active Virtual Meeting Room conferences

Retrieving only those conference instances that are being held in a Virtual Meeting Room is achieved by submitting a GET request to the resource URI for conference status as above, but filtering it by service_type:

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

Getting all participants for a conference

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

The following example finds all participants for the Virtual Meeting Room VMR_1:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/status/v1/participant/?conference=VMR_1",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Active participants for VMR_1:", json.loads(response.text)['objects']

Example output

Active participants for VMR_1: [
    {
    'bandwidth': 576,
    'call_direction': 'in',
    'call_quality': '1_good',
    'call_uuid': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
    'conference': 'VMR_1',
    'connect_time': '2015-04-02T09:46:11.116767',
    'conversation_id': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
    'destination_alias': 'meet@example.com',
    'display_name': 'Alice',
    'encryption': 'On',
    'has_media': False,
    'id': '00000000-0000-0000-0000-000000000002',
    'is_disconnect_supported': true,
    'is_mute_supported': true,
    'is_muted': False,
    'is_on_hold': False,
    'is_presentation_supported': True,
    'is_presenting': False,
    'is_streaming': False,
    'is_transfer_supported': true,
    'license_count': 0,
    'license_type': 'nolicense',
    'media_node': '10.0.0.1',
    'parent_id': '',
    'participant_alias': 'Infinity_Connect_10.0.0.3',
    'protocol': 'WebRTC',
    'proxy_node': '10.10.0.46',
    'remote_address': '10.0.0.3',
    'remote_port': 54686,
    'resource_uri': '/api/admin/status/v1/participant/00000000-0000-0000-0000-000000000002/',
    'role': 'chair',
    'service_tag': '',
    'service_type': 'conference',
    'signalling_node': '10.0.0.1',
    'source_alias': 'Infinity_Connect_10.0.0.3',
    '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': 768,
    'call_direction': 'in',
    'call_quality': '1_good',
    'call_uuid': 'b0a5b554-d1de-11e3-a321-000c29e37602',
    'conference': 'VMR_1',
    'connect_time': '2015-04-02T09:46:53.712941',
    'conversation_id': 'b0a5b554-d1de-11e3-a321-000c29e37602',
    'destination_alias': 'meet@example.com',
    'display_name': 'Bob',
    'encryption': 'On',
    'has_media': False,
    'id': '00000000-0000-0000-0000-000000000003',
    'is_disconnect_supported': true,
    'is_mute_supported': true,
    'is_muted': False,
    'is_on_hold': False,
    'is_presentation_supported': False,
    'is_presenting': False,
    'is_streaming': False,
    'is_transfer_supported': true,
    'license_count': 1,
    'license_type': 'port',
    'media_node': '10.0.0.1',
    'parent_id': '',
    'participant_alias': 'bob@example.com',
    'protocol': 'H323',
    'proxy_node': '',
    'remote_address': '10.0.0.2',
    'remote_port': 11007,
    'resource_uri': '/api/admin/status/v1/participant/00000000-0000-0000-0000-000000000003/',
    'role': 'chair',
    'service_tag': '',
    'service_type': 'conference',
    'signalling_node': '10.0.0.1',
    'source_alias': 'bob@example.com',
    'system_location': 'London',
    'vendor': 'TANDBERG (Tandberg 257)'
    }
    ]

Note that:

  • Perceived call quality:

    • call_quality is the most frequently occurring call quality calculation in the last 3 windows, 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 the media statistics for a participant

Retrieving all the media stream statistics for a participant is achieved by submitting a GET request to the resource URI for the participant status.

The following example finds all media streams for the participant with ID 00000000-0000-0000-0000-000000000002.

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/status/v1/participant/00000000-0000-0000-0000-000000000002/media_stream/",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Media streams for participant:", json.loads(response.text)['objects']

Example output

Media streams for participant: [
    {
    'end_time': '',
    'id': '1',
    'node': '10.0.0.1'
    'rx_bitrate': 513,
    'rx_codec': 'VP8',
    'rx_jitter': 0.29,
    'rx_packet_loss': 0,
    'rx_packets_lost': 0,
    'rx_packets_received': 28761,
    'rx_resolution': '640x480',
    'start_time': '2015-07-22T13:13:52.921269',
    'tx_bitrate': 503,
    'tx_codec': 'VP8',
    'tx_jitter': 7.68,
    'tx_packet_loss': 0,
    'tx_packets_lost': 0,
    'tx_packets_sent': 26041,
    'tx_resolution': '768x448',
    'type': 'video'
    },
    {
    'end_time': '',
    'id': '0',
    'node': '10.0.0.1'
    'rx_bitrate': 12,
    'rx_codec': 'opus',
    'rx_jitter': 0.56,
    'rx_packet_loss': 0,
    'rx_packets_lost': 0,
    'rx_packets_received': 21148,
    'rx_resolution': '',
    'start_time': '2015-07-22T13:13:52.873617',
    'tx_bitrate': 2,
    'tx_codec': 'opus',
    'tx_jitter': 0.21,
    'tx_packet_loss': 0,
    'tx_packets_lost': 0,
    'tx_packets_sent': 42386,
    'tx_resolution': '',
    'type': 'audio'
    }
    ]

Getting the status of a Conferencing Node

By submitting a GET request to the status resource URI of a Conferencing Node you can get its current status. This status will show how an automatic deployment is progressing and the last time the Conferencing Node was configured and contacted.

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/status/v1/worker_vm/1/",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "Conferencing node status:", json.loads(response.text)

Getting the load for a system location

By submitting a GET request to the statistics resource URI of the system location status you can get an estimate of the current media load.

The following example gets the media load for the system location with ID 1:

import json
import requests
response = requests.get(
    "https://<manageraddress>/api/admin/status/v1/system_location/1/statistics/",
    auth=('<user1>', '<password1>'),
    verify=False
    )
print "System Location statistics:", json.loads(response.text)

Getting all registered aliases

Retrieving all the currently registered aliases is achieved by submitting a GET request to the resource URI for registration alias status:

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

Listing all cloud overflow Conferencing Nodes

To retrieve a list of all cloud overflow Conferencing Nodes, submit a GET request to the resource URI for cloud node status:

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

Example output

Cloud nodes: {
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "aws_instance_id": "i-edb1ae65",
      "aws_instance_ip": "172.30.3.6",
      "aws_instance_launch_time": "2016-06-27T23:44:41",
      "aws_instance_name": "aws_overflow1",
      "aws_instance_state": "stopped",
      "cloud_instance_id": "i-edb1ae65",
      "cloud_instance_ip": "172.30.3.6",
      "cloud_instance_launch_time": "2016-06-27T23:44:41",
      "cloud_instance_name": "aws_overflow1",
      "cloud_instance_state": "stopped",
      "max_hd_calls": 0,
      "media_load": 100,
      "resource_uri": "/api/admin/status/v1/cloud_node/i-edb1ae65/",
      "workervm_configuration_id": 6,
      "workervm_configuration_location_name": "AWS",
      "workervm_configuration_name": "aws_overflow1"
    },
    {
      "aws_instance_id": "i-cfb0af47",
      "aws_instance_ip": "172.30.11.83",
      "aws_instance_launch_time": "2016-06-27T23:46:43",
      "aws_instance_name": "aws_overflow2",
      "aws_instance_state": "stopped",
      "cloud_instance_id": "i-cfb0af47",
      "cloud_instance_ip": "172.30.11.83",
      "cloud_instance_launch_time": "2016-06-27T23:46:43",
      "cloud_instance_name": "aws_overflow2",
      "cloud_instance_state": "stopped",
      "max_hd_calls": 0,
      "media_load": 100,
      "resource_uri": "/api/admin/status/v1/cloud_node/i-cfb0af47/",
      "workervm_configuration_id": 7,
      "workervm_configuration_location_name": "AWS",
      "workervm_configuration_name": "aws_overflow2"
    }
  ]
}

Note that:

  • When a Conferencing Node is not available for use (in this example the instances are "stopped"), Pexip Infinity reports a media load of 100% to indicate that there is no current capacity available.
  • The aws_instance prefixed fields are deprecated. Please use the cloud_instance prefixed fields instead.

Listing all locations monitored for dynamic bursting

To list all of the system locations that are being monitored for dynamic bursting, submit a GET request to the resource URI for cloud monitored location status:

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

Example output

Monitored primary locations: {
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "free_hd_calls": 31,
      "id": 4,
      "max_hd_calls": 33,
      "media_load": 5,
      "name": "London",
      "resource_uri": "/api/admin/status/v1/cloud_monitored_location/4/"
    },
    {
      "free_hd_calls": 0,
      "id": 2,
      "max_hd_calls": 42,
      "media_load": 100,
      "name": "Oslo",
      "resource_uri": "/api/admin/status/v1/cloud_monitored_location/2/"
    }
  ]
}

Listing all locations containing dynamic bursting Conferencing Nodes

To list all of the system locations that contain Conferencing Nodes that may be used for dynamic bursting, submit a GET request to the resource URI for cloud monitored location status:

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

Example output

Overflow locations: {
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "free_hd_calls": 31,
      "id": 4,
      "max_hd_calls": 33,
      "media_load": 5,
      "name": "London",
      "resource_uri": "/api/admin/status/v1/cloud_overflow_location/4/"
      "systemlocation_id": 3"
    },
    {
      "free_hd_calls": 0,
      "id": 2,
      "max_hd_calls": 42,
      "media_load": 100,
      "name": "Oslo",
      "resource_uri": "/api/admin/status/v1/cloud_overflow_location/2/"
      "systemlocation_id": 1"
    }
  ]
}