Reporting API
APIs for generating reports.
Generate a Publishing Report
This API generates a publishing report for all streams during an interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Publishing Report Request
Send a PUT
request to /pcast/reporting/publishing
endpoint as shown:
PUT /pcast/reporting/publishing HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 157
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"publishingReport": {
"applicationIds": ["example.com"],
"start": "2020-01-01T00:00:00Z",
"end": "2020-02-01T00:00:00Z"
}
}
Request Headers
Header | Description |
---|---|
Authorization (required) | Use HTTP Basic Authentication with your applicationId and secret |
Request Query Parameters
Name | Description |
---|---|
version (optional) | If used, must be one of the options in Publishing Report Versions, in the format of 'YYYY-MM-dd'. If absent, defaults to 2021-10-20. |
Publishing Report Versions
Version | Description |
---|---|
2021-10-20 | The 2021-10-20 version of the report. |
2021-09-07 | The 2021-09-07 version of the report. |
Request Fields
Field | Description |
---|---|
publishingReport (required) | See PublishingReport object below |
PublishingReport Object
Field | Description |
---|---|
applicationIds (optional) | Array of applications IDs to report for. By default, it will report publishing for the Application ID from credentials. |
streamIds (optional) | Array of stream IDs to report for. Limits the report to just these streams. |
channelIds (optional) | Array of channel IDs to report for. Limits the report to just these channels. |
channelAliases (optional) | Array of channel aliases to report for. Limits the report to just these channels. |
roomIds (optional) | Array of room IDs to report for. Limits the report to just these rooms. |
roomAliases (optional) | Array of room aliases to report for. Limits the report to just these rooms. |
tags (optional) | Array of tags to report for. Limits the report to just these tags. |
start (required) | The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds. |
end (required) | The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds. |
Note: All filter conditions are cumulative.
Publishing Report Response
The response is in CSV format.
Report Response Fields (Default, Version 2021-10-20)
Column | Description |
---|---|
ReportTimestamp | Time of report generation |
PeriodStartTimestamp | Start time of the reporting period |
PeriodEndTimestamp | End time of the reporting period |
ApplicationId | Application ID of the stream |
ChannelAlias | Channel alias of the stream |
ChannelId | Channel ID of the stream |
RoomAlias | Room alias of the stream |
RoomId | Room ID of the stream |
StreamId | Stream ID of the publisher |
Region | Region of the publisher |
AudioQuality | Audio quality of the publisher, or "video-only" if the publisher was video-only |
VideoQuality | Video quality of the publisher, or "audio-only" if the publisher was audio-only |
PublishedMinutesDuringPeriod | The duration published during the report period |
PublishedMinutesTotal | Total duration of the publishing stream, empty if stream did not end within the report period |
FramesPerSecond | Frames per second of the publishing stream |
PeakConcurrentViews | Peak number of concurrent viewing streams |
TotalViews | Total number of viewing streams |
StartTimestamp | Timestamp at which the publishing stream started |
EndTimestamp | Timestamp at which the publishing stream ended |
StartedDuringPeriod | Whether the publishing stream started during the period |
EndedDuringPeriod | Whether the publishing stream ended during the period |
EndedReason | Why the publishing stream ended, empty if stream did not end within the report period |
DeviceId | Unique device ID of the publisher |
RemoteAddress | IP address of the publisher |
ContributionMethod | The method of publishing, either "URI", "RTMP", or "ITP-WebRTC" |
IngestStreamId | Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream |
IngestStreamEndedReason | Why the ingest stream ended, empty if stream did not have a corresponding ingest stream |
IngestSource | Source of the published stream, one of "iOS SDK", "Android SDK", "Web SDK", "Phenix Encoder", "RTMP Encoder", or "Admin API" |
MultiBitrateTranscoding | Whether MultiBitrate transcoding is done for the stream. "TRUE" if either 1) "streaming" capability is set and "streaming-lite" capability is missing, or 2) "on-demand" capability is set and "on-demand-lite" capability is missing, or 3) "multi-bitrate" capability is set. |
Repackaging | Whether repackaging work is done for the stream. "TRUE" if any of the capabilities "streaming", "on-demand", or "rtmp" is present, or if ContributionMethod is "URI" or "RTMP" |
Composition | Whether composition work is done for the stream. "TRUE" if the capability "composition" is set. |
Tags | Tags on the publishing stream |
Capabilities | Capabilities on the publishing stream |
audio_only | Does the publisher have "audio-only" capability |
video_only | Does the publisher have "video-only" capability |
encoding_profile | Encoding profile of the publishing stream |
multi_bitrate | Does the publisher have "multi-bitrate" capability |
multi_bitrate_contribution | Does the publisher have "multi-bitrate-contribution" capability |
streaming | Does the publisher have "streaming" capability |
on_demand | Does the publisher have "on-demand" or "on-demand-archive=PT..." capability |
rtmp | Does the publisher have "rtmp" capability. This capability is no longer in use (was used to support viewers using Flash). |
streaming_lite | Does the publisher have "streaming-lite" capability |
on_demand_lite | Does the publisher have "on-demand-lite" capability |
Report Response Fields (Version 2021-09-07)
Column | Description |
---|---|
ReportTimestamp | Time of report generation |
PeriodStartTimestamp | Start time of the reporting period |
PeriodEndTimestamp | End time of the reporting period |
ApplicationId | Application ID of the stream |
ChannelAlias | Channel alias of the stream |
ChannelId | Channel ID of the stream |
RoomAlias | Room alias of the stream |
RoomId | Room ID of the stream |
StreamId | Stream ID of the publisher |
Region | Region of the publisher |
AudioQuality | Audio quality of the publisher, or "video-only" if the publisher was video-only |
VideoQuality | Video quality of the publisher, or "audio-only" if the publisher was audio-only |
PublishedMinutesDuringPeriod | The duration published during the report period |
PublishedMinutesTotal | Total duration of the publishing stream, empty if stream did not end within the report period |
PeakConcurrentViews | Peak number of concurrent viewing streams |
TotalViews | Total number of viewing streams |
FramesPerSecond | Frames per second of the publishing stream |
StartTimestamp | Timestamp at which the publishing stream started |
EndTimestamp | Timestamp at which the publishing stream ended |
StartedDuringPeriod | Whether the publishing stream started during the period |
EndedDuringPeriod | Whether the publishing stream ended during the period |
EndedReason | Why the publishing stream ended, empty if stream did not end within the report period |
DeviceId | Unique device ID of the publisher |
RemoteAddress | IP address of the publisher |
IngestStreamId | Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream |
IngestStreamEndedReason | Why the ingest stream ended, empty if stream did not have a corresponding ingest stream |
Live | Does the publisher have "streaming" capability |
VOD | Does the publisher have "on-demand" or "on-demand-archive=PT..." capability |
RTMP | Does the publisher have "rtmp" capability. This capability is no longer in use (was used to support viewers using Flash). |
LiveLite | Does the publisher have "streaming-lite" capability |
VODLite | Does the publisher have "on-demand-lite" capability |
MBR | Does the publisher have "multi-bitrate" capability |
MBRContribution | Does the publisher have "multi-bitrate-contribution" capability |
AudioOnly | Does the publisher have "audio-only" capability |
Tags | Tags on the publishing stream |
Capabilities | Capabilities on the publishing stream |
EncodingProfile | Encoding profile of the publishing stream |
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1,494
Content-Disposition: attachment; filename="20200305T161052Z-START20200101T000000Z-END20200201T000000Z-Publishing-fGGvDe.csv"
ReportTimestamp,PeriodStartTimestamp,PeriodEndTimestamp,ApplicationId,ChannelAlias,ChannelId,RoomAlias,RoomId,StreamId,Region,AudioQuality,VideoQuality,PublishedMinutesDuringPeriod,PublishedMinutesTotal,PeakConcurrentViews,TotalViews,FramesPerSecond,StartTimestamp,EndTimestamp,StartedDuringPeriod,EndedDuringPeriod,EndedReason,DeviceId,RemoteAddress,Ingest,Live,VOD,RTMP,LiveLite,VODLite,MBR,MBRContribution,AudioOnly,Tags,Capabilities,EncodingProfile
2020-03-05T16:10:53.769Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,example.com,,us-northeast#example.com#channel123456.S1b486elbH4I,,,us-northeast#US-ASHBURN-AD-1.abc1dmrQ.20191204.LggGuzQ8,us-northeast,,sd,44640,,,,60.12,2019-12-04T12:36:22.476Z,,FALSE,FALSE,,a18af5b7cf914765bd066b13ba842a90953d0bb92bf58c7cfd7b6839b861e5ed,::ffff:52.4.228.111,FALSE,FALSE,TRUE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,channelId:us-northeast#example.com#channel123456.S1b486elbH4I|Status:STREAMING,sd|detached|rtmp|publish-uri,phenix-2020
2020-03-05T16:10:53.769Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,example.com,,,exampleRoomAlias,asia-south#example#roomName.abcdee,asia-south#asia-south1-c.Bqac2GbH.20191203.Vxg6P1AD,asia-south,,sd,44640,,,,59.89,2019-12-03T02:57:15.756Z,,FALSE,FALSE,,3d14957e6209e1c77db3086557d6a42655f8a54ded2a2cea33c9f43506c56297,::ffff:53.5.212.150,FALSE,FALSE,FALSE,FALSE,FALSE,TRUE,FALSE,FALSE,FALSE,x-ingest,publish-uri|resilient|monitor-tracks|no-session-stream-events|transcoding={}|sd|multi-bitrate|prefer-h264|origin-shield,phenix-2020
If the request fails, the platform will return a failed response that contains a "status" field. The HTTP status code is set according to the "status" field.
If a .csv file is created following a failure, that file will include the status message, e.g., {"status":"version-does-not-exist" id:null uri:null filename:null}
HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37
{"status":"excessive-report-interval"}
Publishing report API Response fields
Field | Description |
---|---|
status | See status codes below |
Publishing report API Status Codes
HTTP | Status | Retry | Description |
---|---|---|---|
200 OK | ok | never | Report was successfully created. |
400 Bad Request | varies | never | Indicates an issue with the request. |
400 Bad Request | excessive-report-interval | never | The interval for the report exceed 1 year. |
400 Bad Request | period-start-outside-supported-window | never | The year of the start of period is more than 1 year before the current year. |
400 Bad Request | period-end-must-be-in-past | never | The end of period is in future. |
400 Bad Request | period-end-must-be-after-start | never | The end of period is less than or equal to the start of the period. |
400 Bad Request | malformed-version-in-request-query-parameter | never | The supplied version in HTTP query parameter does not conform to the format "YYYY-MM-dd". |
400 Bad Request | version-does-not-exist | never | The supplied version in HTTP query parameter does not exist, see Publishing Report Versions for supported versions. |
400 Bad Request | unsupported | never | The parameter combination is not supported. |
401 Unauthorized | unauthorized | never | The streaming platform was not able to authorize the provided credentials. |
408 Request Timeout | request-timeout | once immediately, then exponential backoff | Request timed out likely due to temporary resource or network conditions. Please try again. |
4XX | varies | never | Indicates an issue with the request. |
503 Service Unavailable | capacity | once | The system is temporarily overloaded. Please try again later. |
5XX | varies | once immediately, then exponential backoff | A transient server error. |
Error Responses
Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Generate a Viewing Report
This API generates a viewing report for all streams during an interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Viewing Report Request
Send a PUT
request to /pcast/reporting/viewing
endpoint as shown:
PUT /pcast/reporting/viewing HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 174
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"viewingReport": {
"kind": "RealTime",
"applicationIds": ["example.com"],
"start": "2020-01-01T00:00:00Z",
"end": "2020-02-01T00:00:00Z"
}
}
Request Headers
Header | Description |
---|---|
Authorization (required) | Use HTTP Basic Authentication with your applicationId and secret |
Request Fields
Field | Description |
---|---|
viewingReport (required) | See ViewingReport object below |
ViewingReport Object
Field | Description |
---|---|
kind (required) | Kind of viewing report to generate. |
applicationIds (optional) | Array of applications IDs to report for. By default, it will report viewing for the Application ID from credentials. |
streamIds (optional) | Array of stream IDs to report for. Limits the report to just these streams. |
sessionIds (optional) | Array of session IDs to report for. Limits the report to just these sessions. |
originStreamIds (optional) | Array of origin stream IDs to report for. Limits the report to just these origin streams. |
channelIds (optional) | Array of channel IDs to report for. Limits the report to just these channels. |
channelAliases (optional) | Array of channel aliases to report for. Limits the report to just these channel aliases. |
tags (optional) | Array of tags to report for. Limits the report to just these tags. |
originTags (optional) | Array of origin tags to report for. Limits the report to just these origin tags. |
start (required) | The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds. |
end (required) | The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds. |
Note: All filter conditions are cumulative.
ViewingReport Kinds
Field | Description |
---|---|
RealTime | Report for real time viewing. |
RTMP | Report for RTMP viewing. |
HLS | Report for HLS viewing. |
DASH | Report for DASH viewing. |
Viewing Report Response
The response is in CSV format.
Report Response Fields
Column | Description | Real Time | RTMP | HLS | DASH |
---|---|---|---|---|---|
ReportTimestamp | Time of report generation | ✔ | ✔ | ✔ | ✔ |
PeriodStartTimestamp | Start time of the reporting period | ✔ | ✔ | ✔ | ✔ |
PeriodEndTimestamp | End time of the reporting period | ✔ | ✔ | ✔ | ✔ |
ApplicationId | Application ID of the stream | ✔ | ✔ | ✔ | ✔ |
ChannelAlias | Channel alias of the stream | ✔ | ✔ | ✔ | ✔ |
ChannelId | Channel ID of the stream | ✔ | ✔ | ✔ | ✔ |
OriginStreamId | Stream ID of the origin | ✔ | ✔ | ✔ | ✔ |
OriginRegion | Region of the origin | ✔ | ✔ | ✔ | ✔ |
OriginFramesPerSecond | Frames per second of the origin | ✔ | ✔ | ✔ | ✔ |
OriginAudioQuality | Audio quality of the origin, or "video-only" if the origin was video-only | ✔ | ✔ | ✔ | ✔ |
OriginVideoQuality | Video quality of the origin, or "audio-only" if the origin was audio-only | ✔ | ✔ | ✔ | ✔ |
OriginTags | Tags on the origin stream | ✔ | ✔ | ✔ | ✔ |
ViewedMinutesDuringPeriod | The duration viewed during the report period | ✔ | ✔ | ✔ | ✔ |
ViewedMinutesTotal | Total duration of the viewing stream, empty if stream did not end within the report period | ✔ | ✔ | × | × |
TotalBytes | The total bytes bidirectionally transferred for the stream | ✔ | ✔ | ✔ | ✔ |
StartTimestamp | Timestamp at which the viewing stream started | ✔ | ✔ | ✔ | ✔ |
EndTimestamp | Timestamp at which the viewing stream ended | ✔ | ✔ | ✔ | ✔ |
StartedDuringPeriod | Whether the viewing stream started during the period | ✔ |