API - History

Support Center > API Integration

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

Page viewed 2892 times


How can I view session history via the API?


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?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 containing the date specified in the Month parameter. 

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

Gets a list of all sessions used by your company in February 2016 that were conducted with participants whose emails match "testing@securevideo.com".

GET https://api.securevideo.com/history/5?month=2016-02-01&participantEmail=testing@securevideo.com (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 "testing@securevideo.com".


Optionally, 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), and include only sessions which were billable (UTC) in the month containing the date specified in the Month parameter.
  • 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 aa@example.com, and participated in several sessions using that e-mail address, and now has the e-mail address aa@changed.com, you would include the current e-mail address aa@changed.com 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 aa@example.com 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,
"BillableStatusCd": "BILL",
"UserId": 4,
"UsageDescription": "Aaron Johnson Session #105236 with Trevor Stamp - Counted Session"
"SessionId": 105022,
"ScheduleTs": "2016-11-03T22:00:00",
"BillableTs": "2016-11-03T21:56:30.72",
"DurationMinutes": 31,
"BillableStatusCd": "SVCO",
"UserId": 1,
"UsageDescription": "Jonathan Vernon Session #105022 with Dewey Gladstone, Xiao Chu, Marisa Zendejas - Session with SecureVideo.com - does not count towards billable limits"

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 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--the peer-to-peer nature of SecureVideo can make it very difficult to capture the end time of a call given certain combinations of network conditions and events.
  • BillableStatusCd is the current billing state of the session.  If BillableTs is null, then BillableStatusCd will be null also.  If BillableTs is not null, then 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
  • 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, and participants who actually connected to the session.


This article was last reviewed by our Support team on April 19, 2017.