API - History

Support Center > API Integration

Published 02/05/2014 at 5:27pm UTC

Page viewed 32906 times

Details

How can I view session history via the API?

Answer

History API

There is 1 API method available to get your session history:

  • Get History (returns History JSON)

 

Get History (returns History JSON)

GET https://api.securevideo.com/history

Gets a list of all sessions used by your company, across all of your users. 

GET https://api.securevideo.com/history?month=2016-02-01

Gets a list of all sessions used by your company, across all of your users, which were billable (UTC) in the month containing the date specified in the Month parameter. 

GET https://api.securevideo.com/history?month=2016-02-01&[email protected]

Gets a list of all sessions used by your company in February 2016 that were conducted with participants whose emails match "[email protected]".

GET https://api.securevideo.com/history/5?month=2016-02-01&[email protected] (where 5 is host user ID)

Gets a list of all sessions used by your company in February 2016, that were between session host has user ID 5, and participants whose emails match "[email protected]".

GET https://api.securevideo.com/history?startDt=2016-02-04&endDt=2016-02-04

Gets a list of all sessions used by your company, across all of your users, which were billable (UTC) during the time period specified either by month or by a combination of startDt and endDt

 

 

Optional: you can use query string parameters to filter your results further. You can use none, some, or all of these parameters:

  • Month: format should be yyyy-mm-01 (always use first day of month), to include only sessions which were billable (UTC) in the month containing the date specified in the Month parameter.
  • StartDt: format should by yyyy-mm-dd, to include only sessions which were billable (UTC) at or after midnight UTC (00:00) on the indicated start date. If both Month and StartDt are specified, then Month takes precedence.
  • EndDt: format should by yyyy-mm-dd, to include only sessions which were billable (UTC) prior to 11:59:59pm UTC on the indicated end date. If both Month and EndDt are specified, then Month takes precedence.
  • ParticipantEmail: include only sessions which contained a participant who now has the e-mail address specified in the ParticipantEmail parameter. Note that if a participant named Alex Alexis had an e-mail address "[email protected]", and participated in several sessions using that e-mail address, and now has the e-mail address "[email protected]", you would include the current e-mail address "[email protected]" in the query string, and our API server would see that aa.changed.com belongs to Alex Alexis, and would return all sessions including Alex Alexis, even those where the e-mail had been "[email protected]"at the time of the session.

 

History JSON is returned, for example:

[
{
"SessionId": 105236,
"ScheduleTs": "2016-11-03T21:45:09.467",
"BillableTs": "2016-11-03T21:46:16.1",
"DurationMinutes": 25,
"WaitTime": 4,
"BillableStatusCd": "BILL",
"ScheduleType": "OnDemand",
"UserId": 4,
"UsageDescription": "Aaron Johnson Session #105236 with Trevor Stamp - Counted Session",
"ScheduledByUserId": 332,
"ReportableMeetingProvider": "Zoom"
},
{
"SessionId": 105022,
"ScheduleTs": "2016-11-03T22:00:00",
"BillableTs": "2016-11-03T21:56:30.72",
"DurationMinutes": 31,
"WaitTime": 0,
"BillableStatusCd": "SVCO",
"ScheduleType": "Rescheduled",
"UserId": 1,
"UsageDescription": "Iam Demo Session #105022 with George Washington, Alexander Hamilton, James Madison - Session with SecureVideo.com - does not count towards billable limits",
"ScheduledByUserId": null,
"ReportableMeetingProvider": "One-Click"
}
]

History JSON is similar to, but simpler than, Session JSON. Here are the properties for History JSON:

  • SessionId is the unique identifier for the Session
  • ScheduleTs is the date and time that the Session is scheduled for, in UTC.  For "Meet Now" Sessions, the ScheduleTs will be the time that the session was created, and will have a random minutes and seconds component, e.g., 2014-04-16T15:11:22.  For Scheduled Sessions, the ScheduleTs will have 0 seconds, and the minute will be 0, 15, 30, or 45, e.g. 2014-04-16T15:00:00.
  • BillableTs is the time at which the Session becomes a "real" session, in UTC.  While this is called "BillableTs", it does not mean the session will be charged to your company--the session may be later comped by us, or it may count in your included monthly sessions.  A non-null BillableTs means that the session was connected by two people, and is eligible for examination by our billing system to see whether it should be billed.  Once BillableTs is set, it is never changed.  If BillableTs is not set (for a future meeting, or a past one which was never connected to), then null is returned.
  • DurationMinutes
    • If the meeting platform is Zoom with "Join Before Host" turned on, or if the meeting platform is One-Click, this is the number of minutes the session is active. (This includes wait time if the participant or host arrives early before others arrive.)
    • If the meeting platform is Zoom with "Join Before Host" turned off, this is the number of minutes the host was connected to any participant in the session.
    • For sessions which have not yet been deactivated, this number may increase if the session is reconnected later. DurationMinutes will be null if the host is still connected to one or more session participants, or if session end time is unknown. If the end time is known for at least one participant-call, then DurationMinutes will be an integer, the number of minutes that the session host was connected to at least one participant-call whose end time is known. Note that one participant may have multiple participant-calls, for example if the participant left the session and then rejoined. DurationMinutes will be available for most sessions which first connected on or after May 28, 2015, however due to technical causes, we expect to be unable to capture the duration for a small percentage of sessions in a given month.
  • WaitTime
    • For Zoom and One-Click sessions, the subset of DurationMinutes that occurred prior to the BillableTs (which is the time of connection by the second participant). If BillableTs is null, then WaitTime will be equal to DurationMinutes (i.e., the second participant did not connect, so 100% of the DurationMinutes are WaitTime). If the first two participants connect within 1 minute of each other, then WaitTime will be 0.
    • The number of minutes of session after the second participant connects can be expressed as DurationMinutes - WaitTime.
    • If DurationMinutes is null, then WaitTime will be null.
    • WaitTime tracking began on November 25, 2020. For all sessions which are last modified prior to November 25, 2020, the WaitTime will be null.
  • BillableStatusCd is the current billing state of the session. BillableTs will be one of four possible values:
    • BILL - The session counts towards the number of free sessions in a month, and will be charged to your account if beyond that limit
    • SVCO - The session is with SecureVideo.com Support, and does not count towards your monthly session limit
    • DUPL - The session has been flagged by our system as a likely Duplicate, and does not count towards your monthly session limit.  It most likely represents a second attempt to conduct an online session between the same two parties at around the same time.
    • COMP - The session has been comped by our Support team, and does not count towards your monthly session limit
  • ScheduleType is the type of scheduling for the Session, taking one of three possible values for a connected session (available for Sessions modified after 12/23/2020):
    • OnDemand - The session was scheduled On Demand, either using the "New Session Now" dashboard button, an On Demand Virtual Clinic, or an API call.
    • Rescheduled - The session was scheduled and then later rescheduled.
    • Scheduled - A standard scheduled session, where none of the three above Schedule Types are true.
  • UserId is the identifier of the user who hosted the Session.  This UserId can be looked up using the User API.
  • UsageDescription will contain the session description as it appears on invoices and activity downloads in the SecureVideo user interface. It includes a description of the host name, session ID, billable status, duration, wait time, and participants who actually connected to the session.
  • CustomerId is your customer account ID internal to SecureVideo.
  • CustomerName is your customer name within SecureVideo.
  • ScheduledByUserId is the identifier of the user who scheduled the session. The value will be null if no scheduler was involved in scheduling the session. The value will be -1 if the session was scheduled via the SecureVideo API.
  • ReportableMeetingProvider is either "Zoom" or "One-Click". If the meeting switched between video providers, the reportable provider will be the last one used.

 

This article was last reviewed by our Support team on August 31, 2023.