DocumentationRelease Notes
Log In
Documentation

Reporting API

Suggest Edits

The reporting API is designed to enable you to pull reporting data in XML format, suitable for importing into external databases and applications. The data presented is the same as in the session and exit survey reports of the /login administrative interface.

ℹ️

Note

The command API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the API.The API account must have read-only or full access to the command API.

XML data is pulled by sending a simple HTTP request to the BeyondTrust Appliance B Series. The request can be sent using any HTTPS-capable socket library, scripting language module, or a URL fetcher such as cURL or wget. Either GET or POST may be used as the request method.

ℹ️

Note

Even if your B Series Appliance has multiple public sites, all reports return data associated with all public sites unless the request contains a specific parameter to limit the sites pulled.

ℹ️

Note

POST requests must include a "Content-Type: application/x-www-form-urlencoded" HTTP header when supplying parameters in the request body, and the parameters must be url-encoded. Multipart POST requests are not supported.

⚠️

Important

When making consecutive API calls, you must close the connection after each API call.

The reporting API URL is https://support.example.com/api/reporting.

An XML schema which formally describes the format of the returned reporting data is available at https://support.example.com/api/reporting.xsd.

⚠️

Important

To run ArchiveListing or Archive reports, ensure that the Enable Archive API option is checked on the Management > API Configuration page of the /login administrative interface. The state archive API can be enabled independently of other APIs.

generate_report=[string]

The type of report to be generated. Report types can be any of the following:

Archive SupportSession
ArchiveListing SupportSessionListing
CommandShellRecording SupportSessionRecording
JumpItem SupportSessionSummary
LicenseUsage SupportTeam
ShowMyScreenRecording Syslog
SupportCustExitSurvey and SupportRepExitSurvey
VaultAccountActivity  

The reporting API returns XML responses that declare a namespace. If you are parsing these responses with a namespace-aware parser, you will need to set the namespace appropriately or ignore the namespace while parsing the XML.

Reporting API: https://www.beyondtrust.com/namespaces/API/reporting

ℹ️

Note

The above namespace is returned XML data and is not a functional URL.

Archive

The Archive query returns a gzip compressed file with the system state or an event log for a given date and time. The file must be decompressed before it can be parsed. The decompressed file never exceeds 4 GB. History is stored for the past seven active days (days that the B Series Appliance's processes have been running).

State archives are created automatically every thirty minutes, and event archives contain events spanning an interval of ten minutes. Each archive corresponds with an archive listing. Integrations must choose the appropriate archive and replay events from that archive to reconstruct the state at a given point in time.

Archives are not available immediately after the time they represent. It may take a few minutes for a state or event archive to be created. It is helpful to query ArchiveListing before querying Archive to be sure that the archive has been created.

The API account must have the permission Allow Access to Archive Reports.

⚠️

Important

To run ArchiveListing or Archive reports, ensure that the Enable Archive API option is checked on the Management > API Configuration page of the /login administrative interface. The state archive API can be enabled independently of other APIs.

Parameters for archive

type=[string]The type of archive to download. May be either state or event.
date=[YYYY-MM-DD]Specifies the date for which to return the archive.
index=[integer]The index of the archive to download. This index corresponds with the index in ArchiveListing.

JSON response for archive query

The state archive file consists of a single JSON (JavaScript Object Notation) object. Multiple tables and IDs may be specified. If a table does not have any data, its value is null. Possible tables and fields are detailed below.

The event archive file consists of a JSON object for each line in the decompressed file. Events are ordered from oldest to newest in the order in which they actually occurred. Possible tables and fields are detailed below. The following event types are supported:

model_insertCreates a table with all fields included, even if blank.
model_updateAdds or modifies one or more rows in a table.
model_deleteRemoves a table.
truncate_modelSignifies that the B Series Appliance's processes have restarted and that all events logged so far are no longer valid. If any integrations are building data or tables based on the event archive file, they should clean all rows from all tables when this event is received.
session_eventCreates a table with data about events that occurred within the session

JSON tables and fields for model_insert and model_update

customer_client

Stores all customer clients connected to the B Series Appliance. Note that a support_session can exist without a customer_client. This typically occurs when the customer closes the customer client and the representative does not immediately terminate the session in the representative console.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"client_type":"[string]"The type of customer client running on the endpoint or communicating with the endpoint. May be one of desktop, mobile, rdp, vnc, vpro, shell, or web_chat.
"connected":[boolean]1: The customer client is connected to the B Series Appliance.
0: The customer client is not connected. The endpoint system may be rebooting or in the process of elevating.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"elevated":[boolean]1: The customer client is running in an elevated context.
0: The customer client is running in a user context.
"hostname":"[string]"The endpoint's hostname.
"operating_system":"[string]"The endpoint's operating system.
"private_ip":"[string]"The endpoint's private IP address.
"public_ip":"[string]"The endpoint's public IP address.
"support_session_id":[integer]The foreign key that links this table row to other table rows that reference this session.
queue

Stores all active support session queues. A queue is active if one or more of its members are logged in or if it is a persistent queue.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"The code name assigned to the support team. Personal queues do not have code names.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"name":"[string]"The support team's display name.
"support_team_id":"[string]"The support team's unique identifier. The ID is not shown for personal queues.
"type":"[string]"The type of queue. May be one of prewait, team, or personal.
representative

Stores all representatives logged into a representative console.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"connected":[boolean]1: The representative is connected to the B Series Appliance.
0: The representative is not connected to the B Series Appliance.

A representative may be considered logged in even if the representative console is not connected to the B Series Appliance. This could occur if the representative console has lost its connection but the reconnect timeout has not been reached.
"console_in_focus":[boolean]1: The representative console is in focus on the representative's computer.
0: The representative console is not in focus.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"hostname":"[string]"The hostname of the representative's system.
"operating_system":"[string]"The operating system of the representative's system.
"private_display_name":"[string]"The representative's private display name.
"private_ip":"[string]"The private IP address of the representative's system.
"public_display_name":"[string]"The representative's public display name.
"public_ip":"[string]"The public IP address of the representative's system.
"queue_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this queue.
"routing_available":[boolean]1: The representative is available to handle new support sessions.
0: The representative is unavailable to handle new support sessions.
"routing_busy":[boolean]1: The representative has reached their maximum number of support sessions for session assignment.
0: The representative is not marked as busy.
"routing_enabled":[boolean]1: The representative has automatic session assignment enabled.
0: The representative has automatic session assignment disabled.
"routing_idle":[boolean]1: The representative is idle.
0: The representative is active.
"selected_support_session_id":[integer]The ID of the support session currently active in the representative console.

The active support session is recorded once every five seconds. If the representative switches sessions very frequently, some of those session selection change events may not be recorded.
"skill_code_names":"[string]"A comma-separated list of skill code names assigned to this representative.
"type":"[string]"The type of representative connection. May be one of normal or invited.
"user_id":[integer]The representative's unique ID which identifies them in BeyondTrust.
"username":"[string]"The username this representative uses to authenticate to BeyondTrust.
representative_queue

Stores logged-in representatives in relation to their support queues. While team leads and managers have access to their team members' personal queues, that access is not represented in this table.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"queue_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this queue.
"representative_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"role":[string]The user's role in the team. May be one of member, lead, or manager.
representative_support_session

Stores representatives participating in support sessions.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"representative_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"selected_support_session_service_tool":"[string]"The selected support session service tab. May be one of screen_sharing, file_transfer, system_information, remote_shell, or registry.
"support_session_id":[integer]The foreign key that links this table row to other table rows that reference this session.
representative_support_session_tool

Stores a list of support tools in use by representatives in sessions. Rows are added when the representative starts using the tool and are removed when the representative stops using the tool.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"representative_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this representative.
"support_session_id":[integer]The foreign key that links this table row to other table rows that reference this session.
"tool":"[string]"The selected support session service tab. May be one of screen_sharing, file_transfer, system_information, remote_shell, or registry.
support_session

Stores all active support sessions.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"customer_company":"[string]"The end user's company name.
"customer_company_code":"[string]"The end user's company code.
"customer_description":"[string]"The issue description as provided by the customer.
"customer_name":"[string]"The end user's name.
"estimated_pickup_timestamp":[timestamp]The time at which the system expects this session to be accepted or transferred. This could be a time in the past or future.
"issue_code_name":"[string]"The code name of the issue selected by the customer on the front-end survey.
"issue_description":"[string]"The description of the issue selected by the customer on the front-end survey.
"lsid":"[string]"The logging session ID that uniquely identifies this session. This LSID can be used in /login > Reports, with the reporting API, in the integration client, etc.
"primary_team_queue_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this queue. This field stores the last team queue that owned the session before the session ended.
"priority":[integer]The session's priority. May be one of 1 (high), 2 (medium), or 3 (low).
"public_site_id":[integer]The ID of the public site associated with the session.
"public_site_name":"[string]"The name of the public site associated with the session.
"queue_entry_timestamp":[timestamp]The time at which this session entered its current queue.
"queue_id":[integer]The unique ID serving as the foreign key that links this table row with other table rows that reference this queue. This field stores the queue in which the session currently resides.
"start_method":"[string]"The method with which the session was started. May be one of session_key (the seven-digit code or the URL), rep_list, issue_submission, , local_jump, remote_jump, shell_jump, local_rdp, remote_rdp, local_vnc, remote_vnc, or vpro.
support_session_attribute

Stores custom session attributes assigned to active support sessions.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"The code name assigned to the support session attribute.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"support_session_id":[integer]The foreign key that links this table row to other table rows that reference this session.
"value":"[string]"The value of the attribute.
support_session_skill

Stores skills assigned to active support sessions.

(id)An integer that identifies this table row. This ID is unique for the lifetime of the model.
"code_name":"[string]"The code name assigned to the skill.
"created_timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this table row was created.
"support_session_id":[integer]The foreign key that links this table row to other table rows that reference this session.

JSON tables and fields for session_event

These data elements are returned for session events. All but the data element occur for each session event.

"data":[object]Contains details about the session event. These details are described in the tables below.
"lsid":"[string]"The logging session ID that uniquely identifies this session. This LSID can be used in /login > Reports, with the reporting API, in the integration client, etc.
"name":"[string]"The name of the session event. These session events are described in the tables below.
"timestamp":[timestamp]A UNIX timestamp (UTC) representing the time at which this event occurred.
"type":"[string]"The type of table. The value is fixed to session_event for all session events.
callback_button_deployed
"callback_button_id":[integer]The ID of the Support Button that was deployed.
"description":"[string]"The description of the Support Button as entered by the representative.
"expiration":[timestamp]A UNIX timestamp (UTC) representing the time at which the Support Button will expire.
"profile_id":[integer]The ID of the Support Button profile used.
"profile_name":"[string]"The name of the Support Button profile used.
"representative_id":[integer]The unique ID of the representative who deployed the Support Button.
callback_button_removed
"callback_button_id":[integer]The ID of the Support Button that was removed.
"representative_id":[integer]The unique ID of the representative who removed the Support Button.
canned_script_executed
"script_name":"[string]"The name of the canned script that was executed.
chat_message
"body":"[string]"The message to be rendered in the recipient's chat window. The body can contain the %name% macro. Integrations should substitute it with the name of the performed_by member.
"destination":[object]The list of recipients receiving the chat message.
"performed_by":[object]The list of the name-value pairs showing who performed the chat operation.
command_shell_session_started
"download_url":"[string]"The URL to download the command shell recording.
"instance":[integer]The index of the command shell instance.
"representative_id":[integer]The unique ID of the representative who started the command shell operation.
"view_url":"[string]"The URL to view the command shell recording.
customer_exit_survey
"responses":[object]The list of question-answer pairs in the customer exit survey.
directory_created
"destination":[object]The list of name-value pairs showing on which member's system the directory was created.
"failure_reason":"[string]"Optional: The reason the directory creation failed, shown only if an error occurred.
"path":"[string]"The absolute path of the directory.
"performed_by":[object]The list of name-value pairs showing who created the directory.
file_deleted
"destination":[object]The list of name-value pairs showing from which member's system the file was deleted.
"failure_reason":"[string]"Optional: The reason the file deletion failed, shown only if an error occurred.
"name":"[string]"The name of the deleted file.
"performed_by":[object]The list of name-value pairs showing who deleted the file.
"size":[integer]The size of the deleted file, given in bytes.
file_download
"destination":[object]The list of name-value pairs showing to which member's system the file was downloaded.
"name":"[string]"The name of the downloaded file.
"performed_by":[object]The list of name-value pairs showing from which member's system the file was downloaded.
"size":[integer]The size of the downloaded file, given in bytes.
file_download_incomplete
"bytes_transferred":[integer]The number of bytes transferred successfully before the file download failed.
"destination":[object]The list of name-value pairs showing to which member's system the file was being downloaded.
"failure_reason":"[string]"The reason the file download failed.
"name":"[string]"The name of the file being downloaded.
"performed_by":[object]The list of name-value pairs showing from which member's system the file was being downloaded.
file_moved
"destination":[object]The list of name-value pairs showing on which member's system the file was moved.
"failure_reason":"[string]"Optional: The reason the move failed, shown only if an error occurred.
"new_path":"[string]"The absolute path of the file after it was moved.
"old_path":"[string]"The absolute path of the file before it was moved.
"performed_by":[object]The list of name-value pairs showing who moved the file.
file_upload
"destination":[object]The list of name-value pairs showing to which member's system the file was uploaded.
"name":"[string]"The name of the uploaded file.
"performed_by":[object]The list of name-value pairs showing from which member's system the file was uploaded.
"size":[integer]The size of the uploaded file, given in bytes.
file_upload_incomplete
"bytes_transferred":[integer]The number of bytes transferred successfully before the file upload failed.
"destination":[object]The list of name-value pairs showing to which member's system the file was being uploaded.
"failure_reason":"[string]"The reason the file upload failed.
"name":"[string]"The name of the file being uploaded.
"performed_by":[object]The list of name-value pairs showing from which member's system the file was being uploaded.
files_shared
"files":[object]The list of shared files and their attributes. This object contains the following elements:
<name>: The name of the shared file.
<size>: The size of the shared file.
<type>: The file type. Possible values of this field are file and dir.
"performed_by":[object]The list of name-value pairs showing which member shared the files.
legal_agreement_response
"response":"[string]"The action taken by the end-user. Possible values are accept, decline, and timeout.
"text":"[string]"The text of the legal agreement shown in the message box to the customer.
"title":"[string]"The title of the message box where the legal agreement was shown to the customer.
registry_exported
"representative_id":[integer]The unique ID of the representative who exported the registry.
"root_path":"[string]"The root of the exported tree.
registry_imported
"representative_id":[integer]The unique ID of the representative who imported the registry.
registry_key_added
"key":"[string]"The name of the added registry key.
"path":"[string]"The registry key's parent path.
"representative_id":[integer]The unique ID of the representative who added the registry key.
registry_key_deleted
"key":"[string]"The name of the deleted registry key.
"path":"[string]"The registry key's parent path.
"representative_id":[integer]The unique ID of the representative who deleted the registry key.
registry_key_renamed
"new_key":"[string]"The registry key's name after modification.
"old_key":"[string]"The registry key's name before modification.
"path":"[string]"The registry key's parent path.
"representative_id":[integer]The unique ID of the representative who renamed the registry key.
registry_value_added
"data":"[string]"The data of the added registry key value.
"name":"[string]"The name of the added registry key value.
"path":"[string]"The key path to the added registry key value.
"representative_id":[integer]The unique ID of the representative who added the registry key value.
"type":"[string]"The type of the added registry key value data.
registry_value_deleted
"name":"[string]"The data of the deleted registry key value.
"path":"[string]"The key path to the deleted registry key value.
"representative_id":[integer]The unique ID of the representative who deleted the registry key value.
registry_value_modified
"name":"[string]"The name of the modified registry key value.
"new_data":"[string]"The data of the registry key value after modification.
"old_data":"[string]"The data of the registry key value before modification.
"path":"[string]"The key path to the modified registry key value.
"representative_id":[integer]The unique ID of the representative who modified the registry key value.
"type":"[string]"The type of the modified registry key value data.
registry_value_renamed
"new_name":"[string]"The name of the registry key value after modification.
"old_name":"[string]"The name of the registry key value before modification.
"path":"[string]"The key path to the registry key value.
"representative_id":[integer]The unique ID of the representative who renamed the registry key value.
representative_survey
"responses":[object]The list of question-answer pairs in the representative survey.
screen_recording
"download_url":"[string]"The URL to download the screen recording.
"representative_id":[integer]The unique ID of the representative in session during this recording.
"view_url":"[string]"The URL to view the screen recording.
screenshot_captured
"representative_id":[integer]The unique ID of the representative who captured this screenshot.
session_assigned
"representative_id":[integer]The unique ID of the representative who received the session assignment alert.
"timeout":[integer]Optional: The number of seconds before the alert timed out if it was not accepted.
session_assignment_response
"response":"[string]"Text representing the response to the session assignment request.
session_foreground_window_changed
"exe_name":"[string]"The executable name of the foreground window.
"window_name":[string]"The title of the foreground window.
session_note_added
"body":"[string]"The message to be rendered as a session note.
"number":[integer]The index of the session note that was created for this session.
"representative_id":[integer]The unique ID of the representative who added the session note.
show_my_screen_recording
"download_url":"[string]"The URL to download the show my screen recording.
"instance":[integer]The index of the show my screen recording instance.
"representative_id":[integer]The unique ID of the representative showing their screen.
"view_url":"[string]"The URL to view the show my screen recording.
special_action_executed
"action_name":"[string]"The name of the special action that was executed.
system_information_retrieved
"system_information":[object]This object contains multiple data sets, each with a category name, a columns element with a list of field names for the category, and a rows element with field values for each field name.

Use cases

Integrations can use the available data to generate metrics as needed. Below are some examples of how certain metrics could be generated from the data.

Average work time

The average amount of time a representative spends actively working on a single support session. Work time for a single session includes all time where the following are true:

  • The representative console has focus (representative.console_in_focus=true)
  • The support session is selected (representative.selected_support_session_id=support_session.id)
  • The customer client is connected (customer_client.connected=true)
  • The representative is not idle (representative.routing_idle=false)

The average work time can be computed for a set of sessions over a given time range. For example, compute the average work time for all sessions between 8am and 5pm on a given date.

Total active time

The cumulative amount of time the representative was responsible for an active support session. Active time for a single session includes all time where the following are true:

  • The support session is in the representative's personal queue (representative.id=queue.representative_id AND queue.id=support_session.queue_id)
  • The representative is in the support session (representative_support_session.support_session_id=support_session.id AND representative_support_session.representative_id=representative_id)
  • The customer client is connected (customer_client.connected=true)

The total active time is the sum of active time for all sessions over a given time range.

Rep login/out time

When a representative logs in, a new row is inserted into the representative table.

When a representative logs out, a row is removed from the representative table.

The representative.connected field can be used to know when a representative is logged in but not connected.

Number of users logged in during a given period of time

Count the number of rows in the representative table. The period of time can be replayed using the event archive to compute the minimum, maximum, and average number of representatives logged in.

Representative time without a session

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representative table)
  • The representative is not in any support sessions (no rows where representative_support_session.representative_id=representative.id)
  • The representative is connected (representative.connected=true)
Amount of time in concurrent sessions

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representative table)
  • The representative is in X support sessions (X is the number of rows where representative_support_session.representative_id=representative.id)
  • The representative is connected (representative.connected=true)
Time in auto assign mode

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representative table)
  • The representative has auto-assign enabled (representative.routing_enabled=true)
Time available

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representative table)
  • The representative is available for routing (representative.routing_available=true)
Representative time idle

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representative table)
  • The representative is idle (representative.routing_idle=true)
Time waiting for a customer to reconnect

Sum the number of seconds where the following are true:

  • The representative is logged in (has a row in the representativetable)
  • The representative is in the session (representative_support_session.representative_id=representative_id AND representative_support_session.support_session_id=support_session.id)
  • The customer is in the session (customer_client.support_session_id=support_session.id)
  • The customer is not connected (customer_client.connected=false)

Query example for archive

  • Download state archive 50 for November 1 2024
https://support.example.com/api/reporting?generate_report=Archive&type=state&date=2024-11-01&index=50
  • Download event archive 50 for November 1 2024
https://support.example.com/api/reporting?generate_report=Archive&type=event&date=2024-11-01&index=50

ArchiveListing

The ArchiveListing query returns a list of available state archives and event archives for a given date. History is stored for the past seven active days (days that the B Series Appliance's processes have been running).

State archives are created automatically every thirty minutes, and event archives contain events spanning an interval of ten minutes. Each listing represents an archive that is available for download.

Archives are not available immediately after the time they represent. It may take a few minutes for a state or event archive to be created. It is helpful to query ArchiveListing before querying Archive to be sure that the archive has been created.

The API account must have the permission Allow Access to Archive Reports.

⚠️

Important

To run ArchiveListing or Archive reports, ensure that the Enable Archive API option is checked on the Management > API Configuration page of the /login administrative interface. The state archive API can be enabled independently of other APIs.

Parameters for ArchiveListing

date=[YYYY-MM-DD]Specifies the date for which to return a list of archives.

XML response for ArchiveListing Query

<archives>Contains zero or more <state_archive> and/or <event_archive> elements. A state archive contains a snapshot of the system state at a given time. An event archive contains an ordered list of events that occurred between two points in time.

Element names and attributes

/archives/state_archive
<time>The time at which the snapshot of the system's state was taken, returned in ISO 8601 format. Also contains a timestamp attribute which displays the time as a UNIX timestamp (UTC).
<index>The state archive's unique index for the given day. The first state archive of the day always starts at 1. This corresponds with the index of the state archive report.
<event_archive_index>The index of the event archive that starts immediately after the snapshot was taken.
/archives/event_archive
<time>The time of the first possible event in the archive, returned in ISO 8601 format. Also contains a timestamp attribute which displays the start time as a UNIX timestamp (UTC).
<end_time>The time of the last possible event in the archive, returned in ISO 8601 format. Also contains a timestamp attribute which displays the end time as a UNIX timestamp (UTC).
<index>The archive's unique index for the given day. The first event archive of the day always starts at 1. This corresponds with the index of the event archive report.

Query example for ArchiveListing

  • Archive listings for the date of November 1 2024
https://support.example.com/api/reporting?generate_report=ArchiveListing&date=2024-11-01

CommandShellRecording

The CommandShellRecording query returns the requested command shell recording. Depending on your browser, this query will either immediately begin download or prompt you to open or save the file.

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for CommandShellRecording

lsid=[string]The session ID for which you wish to download the video recording of the command shell.
instance=[integer]The instance number of the command shell recording you wish to download. Instances are enumerated starting with 0. The instance number can be obtained from the SupportSession report. Unlike the API, the SupportSession report enumerates instances starting at 1. The instance 1 in a SupportSession report should be referenced as instance 0 in the API.

Query examples for CommandShellRecording

  • CommandShellRecording: First shell instance of session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=CommandShellRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=0
  • CommandShellRecording: brThird shell instance of session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=CommandShellRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=2

JumpItem

The JumpItem query returns full information for all Jump Item events that match given search parameters. You can use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration

The API account must have the permission Allow Access to License Usage Reports.

Parameters for JumpItem

start_date=[YYYY-MM-DD]Specifies that the report returns all events that happened on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report returns all events that happened at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report returns only events that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report returns only events that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration represents days; if start_time or end_time is specified, duration represents seconds.

Optional parameters for JumpItem

jump_group='shared:[id]' or ‘personal:[id]’The numeric ID of the Jump Group or personal group by which to filter Jump Items. Only events performed by Jump Items in the specified group are returned. If this parameter is not specified, results from all Jump Items are returned.
jump_item=[id]:[jump_client, local_jump, remote_jump, local_vnc, remote_vnc, remote_rdp, local_rdp, shell_jump, protocol_tunnel, webjump, vpro]The numeric ID of the Jump Item plus its Jump Item type. While two Jump Items of different types can have the same numeric ID, the ID plus Jump Item type is a unique identifier. Only events for the specified Jump Item are returned. If this parameter is not specified, results from all Jump Items are returned.
performed_by='user:[id]' or ‘api_account:[id]’ or ‘system’The numeric ID of the user or API account that performed the Jump Item event. Only events performed by the specified actor are returned. If system is specified, only Jump Item events initiated by the Privileged Remote Access software itself are returned. If this parameter is not specified, results from all actors are returned.

XML response for JumpItem query

<jump_item_event_list>Contains a <jump_item_event> element for each event that matches the given criteria. If no events are returned, this element contains no <jump_item_event> elements. If an error occurs during the search, it contains an <error> element describing the problem.

Element names and attributes
<timestamp> The system time at which the event occurred. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the start time as a UNIX timestamp (UTC).
<jump_item> The ID of the Jump Item.
<jump_item_name> The name of the Jump Item.
<event_type> The type of event which occurred. Event types include the following:
Jump Item 2FA Authentication Failed Jump Item Copied To
Jump Item Authorization Approved Jump Item Created
Jump Item Authorization Canceled Jump Item Deleted
Jump Item Authorization Denied Jump Item Moved From
Jump Item Authorization Expired Jump Item Moved To
Jump Item Authorization Requested Jump Item Session Started
Jump Item Copied From
<jump_item_type> The Jump Item type of the event
<jump_group> The element's content is the name of the Jump Group. For Personal Jump Groups, the name of the Jump Group is the Private Display Name of the representative who owns the Jump Group. The <jump_group> element has two attributes:
type: This is the Jump Group's type, which can be "shared" or "personal".
id: This is the Jump Group's unique ID for its type. Jump Groups of different types can have the same ID. For Personal Jump Groups, this is the unique ID of the user who owns the Jump Group. Each user can only have a single Personal Jump Group.
<performed_by> The entity that caused the event. Indicates the entity’s ID and also its type, indicating whether this action was performed by the system, a representative, or an API account.
<data> The content of this element depends on the event_type. For example, a Jump Item Session Started even will include the LSID of the session.

Query examples for JumpItem

  • Events started November 1 2024 to present
https://support.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0
  • Events started the month of November 2024
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=31
  • brEvents started 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_time=1730448000&brduration=0
  • Events started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_time=1730448000&brduration=36000
  • Events started November 1 2024 to present for a specific Jump Group
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=0&jump_group='personal:1'
  • Events started November 1 2024 to present for a specific Jump Item
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=0&jump_item=1:jump_client
  • Events started November 1 2024 to present for a specific actor
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=0&performed_by='user:1'
  • Events started November 1 2024 to present for a specific Jump Group and for a specific actor
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=0&jump_group='shared:1'&performed_by='api_account:1'
  • Events started November 1 2024 to present for a specific Jump Item and a specific actor
https://support.example.com/api/reporting?brgenerate_report=JumpItem&start_date=2024-11-01&brduration=0&jump_item=1:local_rdp&performed_by='system'

LicenseUsage

The LicenseUsage query returns an overview of peak license usage times, grouped by hour, day, or month. Data is added to this report when at least 90% of your BeyondTrust licenses are in use. You may use any of the following sets of parameters to generate reports:

  • start_date, duration, and group_by
  • start_time, duration, and group_by

The API account must have the permission Allow Access to License Usage Reports.

Parameters for LicenseUsage

start_date=[YYYY-MM-DD]Specifies that the report should return peak license usage data beginning on or after this date.
start_time=[timestamp]Specifies that the report should return peak license usage data beginning at or after this time. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date is specified, duration represents days; if start_time is specified, duration represents seconds.
group_bySpecifies whether the data should be grouped by hour, day, or month.

XML response for LicenseUsage query

<license_usage>Contains a <license_time_intervals> element. If no license usage data is returned, this element will contain no license usage elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Also contains <start_time> and <end_time> elements displaying the time parameters in the system time and with a timestamp attribute in UTC. A <group_by> element shows whether the data is grouped by hour, day, or month.

Element names and attributes

/license_usage/license_time_intervals
<license_time_interval>Contains a <license_time_interval> element for each time at which peak license usage was logged.
/license_usage/license_time_intervals/license_time_interval
timestamp (attribute)The timestamp at which peak license usage was logged.
datetime (attribute)The date and time at which peak license usage was logged.
<license_count>Contains a <license_count> element for each potential type of license usage. This displays the number of licenses in use at that time.
/license_usage/license_time_intervals/license_time_interval/license_count
license_type (attribute)The type of license used by the representative.
reason (attribute)Can be either login or extended_contact, or this attribute may not be present. The login reason indicates that a license was in use due to a user being logged into the representative console. The extended_contact reason indicates that a license was being consumed due to a user being in extended availability mode. If no reason is listed, the license count is the total number of licenses in use.

Query examples for LicenseUsage

  • License usage starting November 1 2024 to present, grouped by hour
https://support.example.com/api/reporting?generate_report=LicenseUsage&start_date=2024-11-01&duration=0&group_by=hour
  • License usage during the month of November 2024, grouped by day
https://support.example.com/api/reporting?generate_report=LicenseUsage&start_date=2024-11-01&duration=31&group_by=day
  • License usage starting 8:00 AM November 1 2024 to present, grouped by month
https://support.example.com/api/reporting?generate_report=LicenseUsage&start_time=1730448000&duration=0&group_by=month
  • License usage starting 8:00 AM November 1 2024 to 6:00 PM November 1 2024, grouped by hour
https://support.example.com/api/reporting?generate_report=LicenseUsage&start_time=1730448000&duration=36000&group_by=hour

ShowMyScreenRecording

The ShowMyScreenRecording query returns the requested Show My Screen recording. Depending on your browser, this query will either immediately begin download or prompt you to open or save the file.

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for ShowMyScreenRecording

lsid=[string]The session ID for which you wish to download the video recording of the Show My Screen session.
instance=[integer]The instance number of the Show My Screen recording you wish to download. Instances are enumerated starting with 0. The instance number can be obtained from the SupportSession report.

Query examples for ShowMyScreenRecording

  • ShowMyScreenRecording: First instance of session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=ShowMyScreenRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=0
  • ShowMyScreenRecording: brThird instance of session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=ShowMyScreenRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=2

SupportCustExitSurvey and SupportRepExitSurvey

The SupportCustExitSurvey and SupportRepExitSurvey queries return the questions and answers to the customer or representative survey. You may use any of the following sets of parameters to generate reports:

  • start_date, duration, report_type, and id
  • start_time, duration, report_type, and id
  • end_date, duration, report_type, and id
  • end_time, duration, report_type, and id
  • lsid and report_type
  • lsids and report_type

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for SupportCustExitSurvey and SupportRepExitSurvey

start_date=[YYYY-MM-DD]Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.
report_type=[string]Enter rep to filter results according to the representative who last owned the session or team to filter according to team.
id=[integer]May be the numeric ID of the representative or team that you wish to view or "all" to display data for all representatives or teams.

To get a representative's ID, see get_logged_in_reps. To get a team's ID, see get_support_teams.
lsid=[string]The session ID for which you wish to see the survey report.
lsids=[comma-separated strings]A comma-delimited list of the session IDs for which you wish to see survey reports.

Optional parameter

site_id=[integer]The numeric ID of the public site by which to filter results. Only surveys whose support sessions are associated with the given public site are returned. If this parameter is not specified, results from all public sites are returned. The default public site always has an ID of 1.

XML response for SupportCustExitSurvey and SupportRepExitSurvey queries

<exit_survey_list>Contains an <exit_survey> element for each session that matches the given criteria. If no sessions are returned, this element will contain no <exit_survey> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Element names and attributes

/exit_survey_list/exit_survey
lsid (attribute)The unique ID of the session for which this survey was submitted.
ts (attribute)The start time of the session for which this survey was submitted.
<session_type>Indicates the type of session for which the report was submitted. This value will always be support in the current BeyondTrust API version.
<public_site>The name of the public site associated with the session. Also contains an id attribute, which displays the unique ID assigned to the public site..
<submitted_by>The name of the customer or private display name of the representative who submitted the survey. This element also has a type attribute with the value of cust or rep, indicating whether this survey was submitted by a customer or a representative.
<primary_customer>The display name of the customer who initiated the session. This element also has an id attribute, the value of which is always 0.
<primary_rep>The private display name of the final representative to own the session, as it appeared at the time of the session. This element also has an id attribute, which is the representative’s unique ID. This element will be absent if the customer closed the session before it was accepted by a representative.
<primary_team>The display name of the last team to which the session was transferred. This element also has an id attribute, which is the team’s unique ID. This element will be absent if the session was never transferred to a team.
<customer_list>Listing of all customers who participated in this session. For full details, see the descriptions of the <customer_list> and <customer> elements in the SupportSession section.
<rep_list>Listing of all representatives who participated in this session. For full details, see the descriptions of the <rep_list> and <representative> elements in the SupportSession section.
<team_list>Listing of all teams to which the session was transferred. For full details, see the descriptions of the <team_list> and <team> elements in the SupportSession section.
<rep_resolved>This element is present for backwards compatibility. In the BeyondTrust API versions 1.0.0 and above, this value will always be 0.
<question_list>Contains a <question> element for each question in this survey. This element contains several child elements as described below. Note that the <question> elements and their child <answer> elements are displayed as they are currently configured in the administrative interface. If a question was edited since the time of the first returned survey, the answers may not appear exactly as they were submitted.
/exit_survey_list/exit_survey/question_list/question
id (attribute)The unique ID of this question.
<name>The name of the question as used to identify it within the web interface.
<type>The type of question, which can be radio, checkbox, select, text or textarea.
<label>The question text as displayed to the user taking the survey.
<report_header>The value used to identify this question in the report.
<answer_list>Listing of <answer> elements entered by the user. Radio, text, and textarea questions have a maximum of one <answer>. Checkbox and select questions may have more than one <answer> if multiple selection is enabled.
/exit_survey_list/exit_survey/question_list/question/answer_list
<answer>The answer entered by the user. For radio, checkbox and select questions, this is the logged value for the selected options. For text and textarea types, it is the text typed by the user. If the question is unanswered, it will be blank.

Query examples for SupportCustExitSurvey and SupportRepExitSurvey

  • Customer surveys for sessions started November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=all
  • Customer surveys for sessions started November 1 2024 to present for all teams, by team
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=0&report_type=team&id=all
  • Customer surveys for sessions started November 1 2024 to present for a specific rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=1
  • Customer surveys for sessions started November 1 2024 to present for a specific team
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=0&report_type=team&id=1
  • Customer surveys for session started the month of November 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=31&report_type=rep&id=all
  • Customer surveys for sessions started 8:00 AM November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_time=1730448000&duration=0&report_type=rep&id=all
  • Customer surveys for session started 8:00 AM November 1 2024 to 6.00 PM November 1 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_time=1730448000&duration=36000&report_type=rep&id=all
  • Customer surveys for sessions ended November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&end_date=2024-11-01&duration=0&report_type=rep&id=all
  • Customer surveys for session ended the month of November 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&end_date=2024-11-01&duration=31&report_type=rep&id=all
  • Customer surveys for sessions ended 8:00 AM November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&end_time=1730448000&duration=0&report_type=rep&id=all
  • Customer surveys for session ended 8:00 AM November 1 2024 to 6.00 PM November 1 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&end_time=1730448000&duration=36000&report_type=rep&id=all
  • Customer surveys for sessions started November 1 2024 to present for all reps, by rep, for a specific site
https://support.example.com/api/reporting?generate_report=SupportCustExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=all&site_id=1
  • Representative surveys for sessions started November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=all
  • Representative surveys for sessions started November 1 2024 to present for all teams, by team
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=0&report_type=team&id=all
  • Representative surveys for sessions started November 1 2024 to present for a specific rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=1
  • Representative surveys for sessions started November 1 2024 to present for a specific team
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=0&report_type=team&id=1
  • Representative surveys for session started the month of November 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=31&report_type=rep&id=all
  • Representative surveys for sessions started 8:00 AM November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_time=1730448000&duration=0&report_type=rep&id=all
  • Representative surveys for session started 8:00 AM November 1 2024 to 6.00 PM November 1 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_time=1730448000&duration=36000&report_type=rep&id=all
  • Representative surveys for sessions ended November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&end_date=2024-11-01&duration=0&report_type=rep&id=all
  • Representative surveys for session ended the month of November 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&end_date=2024-11-01&duration=31&report_type=rep&id=all
  • Representative surveys for sessions ended 8:00 AM November 1 2024 to present for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&end_time=1730448000&duration=0&report_type=rep&id=all
  • Representative surveys for session ended 8:00 AM November 1 2024 to 6.00 PM November 1 2024 for all reps, by rep
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&end_time=1730448000&duration=36000&report_type=rep&id=all
  • Representative surveys for sessions started November 1 2024 to present for all reps, by rep, for a specific site
https://support.example.com/api/reporting?generate_report=SupportRepExitSurvey&start_date=2024-11-01&duration=0&report_type=rep&id=all&site_id=1

SupportSession

The SupportSession query returns full information for all sessions which match given search parameters. You may use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration
  • lsid
  • lsids

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for SupportSession

start_date=[YYYY-MM-DD]Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.
lsid=[string]The ID of the session for which you wish to see details.
lsids=[comma-separated strings]A comma-delimited list of the IDs of sessions for which you wish to see details.

Optional parameter for SupportSession

limit=[string]

The category by which to filter results. Can be one of the following:

all Returns all results.
rep:[id] Returns sessions owned by a representative, specified by user ID.
team:[all] Returns sessions owned by any team.
team:[id] Returns sessions owned by a team specified by team ID.
members:[id] Returns sessions owned by members of a team specified by team ID.
site:[id] Returns sessions run through a public site specified by site ID. The default public site always has an ID of 1.

The limit parameter cannot be used in conjunction with either lsid or lsids. If it is used with either of these parameters, the limit parameter will be ignored.

XML response for SupportSession query

<session_list>Contains a <session> element for each session that matches the given criteria. If no sessions are returned, this element will contain no <session> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Element names and attributes

/session_list/session
lsid (attribute)A string which uniquely identifies this session.
<session_type>Indicates the type of session for which the report was run. The value will always be support in the current BeyondTrust API version.
<lseq>An incrementing number used to represent support sessions in a non-string format.
The LSEQ element is not guaranteed to be unique or strictly sequential.
<start_time>The date and time the session was begun either by the customer’s running the customer client or by the representative’s initiating a Jump session. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the start time as a UNIX timestamp (UTC).
<end_time>The date and time the session was ended either by the customer’s closing the customer client or by the representative’s closing the session. Data is returned in ISO 8601 format. Also contains a timestamp attribute which displays the end time in UNIX timestamp (UTC). This element will be empty for sessions which are still in progress when the report was run or which closed abnormally.
<duration>Session length in HH:MM:SS format.
<public_site>The name of the public site associated with the session. Also contains an id attribute, which displays the unique ID assigned to the public site.
<jumpoint>The name of the Jumpoint through which this session was initiated, if any. Also contains an id attribute, which displays the unique ID assigned to the Jumpoint.
<external_key>An arbitrary string that can link this session to an identifier on an external system, such as a help desk ticket ID. This can be input from within the representative console or defined programmatically.
<custom_attributes>Contains a <custom_attribute> element for each custom field assigned to a session. This element displays only if custom fields have been defined. The format of each <custom_attribute> element is described below.
<session_chat_view_url>The URL at which this session’s chat transcript can be viewed in a web browser. This element is displayed only for sessions that have successfully ended.
<session_chat_download_url>The URL at which this session’s chat transcript can be downloaded. This element is displayed only for sessions that have successfully ended.
<session_recording_view_url>The URL at which the video of the session may be viewed in a web browser. This element is displayed only if screen sharing recording was enabled at the time of the session. It is available only for sessions that have successfully ended and only if the requesting user has permission to view session recordings.
<session_recording_download_url>The URL at which the video of the session may be downloaded. This element is displayed only if screen sharing recording was enabled at the time of the session and only if the rep initiated screen sharing during the session. It is available only for sessions that have successfully ended and only if the requesting user has permission to view session recordings.
<show_my_screen_recordings>Contains a <show_my_screen_recording> element for each Show My Screen session that was initiated during the session. This element is displayed only if the representative shared their screen during the session, if Show My Screen recording was enabled at the time of the session, and only if the requesting user has permission to view Show My Screen recordings. Each <show_my_screen_recording> element contains the child elements <download_url> and <view_url> as described below.
<command_shell_recordings>Contains a <command_shell_recording> element for each command shell that was initiated during the session. This element is displayed only if the representative opened a remote command shell during the session, if command shell recording was enabled at the time of the session, and if the requesting user has permission to view session recordings. Each <command_shell_recording> element contains the child elements <download_url> and <view_url> as described below.
<file_transfer_count>The number of file transfers which occurred during the session.
<file_move_count>The number of files renamed via the File Transfer interface during the session.
<file_delete_count>The number of files deleted via the File Transfer interface during the session.
<primary_customer>Lists the gsnumber as an attribute and as an element the name of the customer who initiated the session or, for a Jump session, the computer name of the remote system accessed by the representative.
<primary_rep>Lists the gsnumber and id as attributes, and as an element the name of the final representative to own the session. If the session closed before it was transferred to a representative, this element will not be displayed. 
<primary_team>Lists the team ID and name of the final team to which this session was transferred. If the session was never transferred to a team, this element will not be displayed.
<customer_list>A list of all customers who participated in the session. There should always be exactly one customer per session in the current BeyondTrust API version. The format of each <customer> element is described below.
<rep_list>A list of all representatives who participated in the session, whether as session owners or conference members. The format of each <representative> element is described below. If the customer closed the session before it was transferred to a representative, this element will be empty.
<team_list>A list of all teams to which the session belonged, whether by the session being initiated in a team queue, by a representative’s explicitly transferring the session to a team, or by a session falling back into a team queue after a lost connection. This element may be empty, or it may contain one or more <team> elements as described below.
<cust_survey_list>Contains a <cust_exit_survey> element if a customer exit survey was completed. This element is displayed only for sessions that have successfully ended and only if the customer submitted the survey. This element contains several child elements.
<rep_survey_list>Contains a <rep_exit_survey> element if a representative survey was completed. This element is displayed only for sessions that have successfully ended and only if the representative submitted the survey. This element contains several child elements.
<session_details>Contains a chronological list of all events which occurred during the session. This element contains one or more child <event> elements.
/session_list/session/custom_attributes/custom_attribute
display_name (attribute)The display name assigned to the custom attribute.
code_name (attribute)The code name assigned to the custom attribute.
/session_list/session/show_my_screen_recordings/show_my_screen_recording
instance (attribute)The instance of the Show My Screen session, starting with 0.
<download_url>The URL at which the video of the Show My Screen session may be downloaded.
<view_url>The URL at which the video of the Show My Screen session may be viewed in a web browser.
/session_list/session/command_shell_recordings/command_shell_recording
instance (attribute)The instance of the command shell session, starting with 0.
<download_url>The URL at which the video of the command shell session may be downloaded.
<view_url>The URL at which the video of the command shell session may be viewed in a web browser.
/session_list/session/customer_list/customer
gsnumber (attribute)Uniquely identifies the customer in regards to their current connection to the B Series Appliance. A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <customer> element with a <primary_cust> or with an event’s <performed_by> or <destination> element.
<username>The name used to identify the customer during the session. The method used to obtain this name varies depending on how the session was started.
<public_ip>The customer’s public IP address.
<private_ip>The customer’s private IP address.
<hostname>The hostname of the customer’s computer.
<os>The operating system of the customer’s computer.
<primary_cust>Integer value (1 or 0) indicating if this customer was the first customer of the session. In the current version of the BeyondTrust API, this value is always 1.
<info>Contains detailed information about the customer as either entered in the front-end survey or designated programmatically. This field contains several child elements as described below.
/session_list/session/customer_list/customer/info
<name>The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically.
<company>The company name which the customer entered in the Company field on the front-end survey or which was assigned programmatically.
<company_code>The code which the customer entered in the Company Code field on the front-end survey or which was assigned programmatically.
<issue>The numeric ID of the issue or the representative which the customer selected from the dropdown of the front-end survey or which was designated programmatically.
<details>The description of the problem as entered by the customer in the Describe Your Issue text area field of the front-end survey or as programmatically assigned.
/session_list/session/rep_list/representative
gsnumber (attribute)Uniquely identifies the representative in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber is assigned on a per-connection basis, so if a representative leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same.

However, if the representative’s connection is terminated for any reason, when that representative logs back into the B Series Appliance, they will be assigned a new gsnumber and will also appear multiple times in the <rep_list> element.

A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <representative> element with a <primary_rep> or with an event’s <performed_by> or <destination> element.
id (attribute)Unique ID assigned to the representative.
<username>The username assigned to the representative.
<display_name>This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <private_display_name>.
<public_display_name>The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed.
<private_display_name>The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed.
<display_number>The display number assigned to the representative. Like <display_name>, this is the display number at the time of the session and may not match the current value.
<public_ip>The representative’s public IP address.
<private_ip>The representative’s private IP address.
<hostname>The hostname of the representative’s computer.
<os>The operating system of the representative’s computer.
<session_owner>Integer value (1 or 0) indicating whether the representative was an actual owner of the session or was merely a conference member.
<primary_rep>Integer value (1 or 0) indicating if the representative was the final representative to own the session.
<seconds_involved>Integer value indicating the number of seconds the representative was involved in this session.
<invited>Integer value (1) present only if the representative is an invited user.
/session_list/session/team_list/team
[value]The display name of the support team. Note that this field contains the team name as it currently appears, which may not match the value at the time of the session if the team name has been subsequently changed.
id (attribute)Integer value representing the team’s unique ID.
primary_team (attribute)Integer value (1 or 0) indicating if this team was the last team to which the session was transferred.
/session_list/session/session_details/event
timestamp (attribute) The system time at which the event occurred.
event_type (attribute)

The type of event which occurred. Event types include the following:

Callback Button Deployed Files Shared
Callback Button Removed Legal Agreement Response
Chat Message Registry Exported
Command Shell Session Started* Registry Imported
Conference Member Added Registry Key Added
Conference Member Departed Registry Key Deleted
Conference Member State Changed Registry Key Renamed
Conference Owner Changed Representative Exit Survey
Customer Exit Survey Service Access Allowed
Directory Created Session Assigned
External Key Session Assignment Response
File Deleted Session End
File Download Session Foreground Window Changed
File Download Failed Session Note Added
File Moved Session Start
File Upload Show My Screen Recording
File Upload Failed System Information Retrieved

*Will only appear if recording is enabled for this session.
<performed_by> The entity that performed the action. Indicates the entity’s gsnumber and also its type, indicating whether this action was performed by the system, a customer, or a representative.
<destination> The entity to which the event was directed. Indicates the entity’s gsnumber and also its type, indicating whether this action was directed to the system, a customer, or a representative.
<body> The text of the message as displayed in the chat log area.
<encoded_body> Can be shown in place of the <body> element above. Contains the base64 (RFC 2045 section 6.8) encoded value of what would have been shown in the <body> element, and is shown ONLY if the <body> text contains characters that are invalid according to XML specification. These characters are typically the result of binary data being sent through chat messages.
<filename> The name of the transferred file.
<filesize> An integer indicating the size of the transferred file.
<system_information>

Applies only to System Information Retrieved events wherein the system information is pulled automatically upon session start. This element contains multiple <category> child elements as described below.

System information is logged only when pulled automatically at the beginning of the session and not when specifically requested by the representative. This is to prevent overload with the large amount of dynamic data that can be retrieved from the remote system.
<files> If this event involved the transferring of files, then this element will contain a <file> element for every file transferred.
<data> Contains an arbitrary number of <value name="_" value="_" /> elements. The name and number of these elements varies based on event_type. For example, when a representative joins the session, a Conference Member Added event would contain <value> elements for the representative’s name, username, private_ip, public_ip, hostname, os, support_teams, and user_id.
/session_list/session/session_details/event/system_information/category
<description>Contains multiple <field> elements, each of which contains a descriptor for the specific data field. For example, the Drives category would have <field> elements Drive, Type, Percent Used, etc. These <field> elements can be compared to table header cells.
<data>Contains multiple <row> elements, each of which contains multiple <field> elements that correspond to the <field> elements above. For example, the Drives category would have a separate <row> for each drive on the remote computer. An example <row> might contain <field> elements C:\, Local Disk, 60%, etc. These <row> elements can be compared to table rows, with each <field> element a table cell.

Query examples for SupportSession

  • Sessions started November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0
  • Sessions started the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=31
  • Sessions started 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSession&start_time=1730448000&duration=0
  • Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportSession&start_time=1730448000&duration=36000
  • Sessions ended November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSession&end_date=2024-11-01&duration=0
  • Sessions ended the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportSession&end_date=2024-11-01&duration=31
  • Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportSession&end_time=1730448000&duration=36000
  • Session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=SupportSession&lsid=c69a8e10bea9428f816cfababe9815fe
  • Sessions c69a8e10bea9428f816cfababe9815fe, a5eeaa58591047b88556f944804227b0, br5bf07601298b495b87310da9ce571e22
https://support.example.com/api/reporting?generate_report=SupportSession&lsids=c69a8e10bea9428f816cfababe9815fe,a5eeaa58591047b88556f944804227b0,5bf07601298b495b87310da9ce571e22
  • Sessions started November 1 2024 to present for all sessions
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=all
  • Sessions started November 1 2024 to present for a specific rep
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=rep:1
  • Sessions started November 1 2024 to present for all teams
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=team:all
  • Sessions started November 1 2024 to present for a specific team
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=team:1
  • Sessions started November 1 2024 to present for members of a specific team
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=members:1
  • Sessions started November 1 2024 to present for a specific public site
https://support.example.com/api/reporting?generate_report=SupportSession&start_date=2024-11-01&duration=0&limit=site:1

SupportSessionListing

The SupportSessionListing query returns a list of session IDs, external keys, and availability of a recording for sessions which match given search parameters. You may use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for SupportSessionListing

start_date=[YYYY-MM-DD]Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.

XML response for SupportSessionListing query

<session_summary_list>Contains a <session_summary> element for each session that matches the given criteria. If no sessions are returned, this element will contain no <session_summary> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Element names and attributes

/session_summary_list/session_summary
lsid (attribute)The session ID for the given support session.
<lseq>An incrementing number used to represent support sessions in a non-string format.

The LSEQ element is not guaranteed to be unique or strictly sequential.
has_recording (attribute)Integer (1 or 0) indicating if the given session has a session recording.
external_key (attribute)An arbitrary string that can link this session to an identifier on an external system, such as a help desk ticket ID. This can be input from within the representative console or defined programmatically. This element will be displayed only if an external key has been defined.

Query examples for SupportSessionListing

  • Sessions started November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSessionListing&start_date=2024-11-01&duration=0
  • Sessions started the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportSessionListing&start_date=2024-11-01&duration=31
  • Sessions started 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?generate_reportt=SupportSessionListing&start_time=1730448000&duration=0
  • Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportSessionListing&start_time=1730448000&duration=36000
  • Sessions ended November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSessionListing&end_date=2024-11-01&duration=0
  • Sessions ended the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportSessionListing&end_date=2024-11-01&duration=31
  • Sessions ended 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportSessionListing&end_time=1730448000&duration=0
  • Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportSessionListing&end_time=1730448000&duration=36000

SupportSessionRecording

The SupportSessionRecording query returns the requested support session recording file. Depending on your browser, this query will either immediately begin download or prompt you to open or save the file.

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameter for SupportSessionRecording

lsid=[string]The session ID for which you wish to download the video recording of the support session.

Query example for SupportSessionRecording

  • SupportSessionRecording: Session c69a8e10bea9428f816cfababe9815fe
https://support.example.com/api/reporting?generate_report=SupportSessionRecording&lsid=c69a8e10bea9428f816cfababe9815fe

SupportSessionSummary

The SupportSessionSummary query returns an overview of support session statistics for representatives, teams or sites. You may use any of the following sets of parameters to generate reports:

  • start_date, duration, and report_type
  • start_time, duration, and report_type
  • end_date, duration, and report_type
  • end_time, duration, and report_type

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for SupportSessionSummary

start_date=[YYYY-MM-DD]Specifies that the report should return all sessions, even those still in progress, that began on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report should return all sessions, even those still in progress, that began at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report should return only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report should return only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.
report_type=[string]Accepted values are rep (to show representative summary statistics), team (to show team summary statistics), or site (to show public site summary statistics).

XML response for SupportSessionSummary query

<summary_list>Contains a <summary> element for each record that matches the given criteria. If no sessions are returned, this element will contain no <summary> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Element names and attributes

/summary_list/summary
id (attribute)Returns the representative’s, team’s, or site’s unique ID.
type (attribute)Specifies the report type being generated: rep, team, or site.
<display_name>The display name of the team or site, or the private display name of the representative. Note that since summary reports represent an aggregation of sessions over a period of time, the display name used is the current value for the representative, team, or site, which may have been edited since the time of the first returned session.
<total_sessions>The total number of sessions run by the rep, team, or site in the time specified.
<avg_sessions_per_weekday>The average number of sessions conducted on Monday through Friday by the representative, team, or site, expressed as a decimal rounded to the nearest point.
<avg_duration>The average length of each session, expressed as HH:II:SS.

Query examples

  • Sessions started November 1 2024 to present, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_date=2024-11-01&duration=0&report_type=rep
  • Sessions started November 1 2024 to present, by team
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_date=2024-11-01&duration=0&report_type=team
  • Sessions started November 1 2024 to present, by site
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_date=2024-11-01&duration=0&report_type=site
  • Sessions started the month of November 2024, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_date=2024-11-01&duration=31&report_type=rep
  • Sessions started 8:00 AM November 1 2024 to present, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_time=1730448000&duration=0&report_type=rep
  • Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&start_time=1730448000&duration=36000&report_type=rep
  • Sessions ended November 1 2024 to present, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&end_date=2024-11-01&duration=0&report_type=rep
  • Sessions ended the month of November 2024, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&end_date=2024-11-01&duration=31&report_type=rep
  • Sessions ended 8:00 AM November 1 2024 to present, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&end_time=1730448000&duration=0&report_type=rep
  • Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024, by rep
https://support.example.com/api/reporting?generate_report=SupportSessionSummary&end_time=1730448000&duration=36000&report_type=rep

SupportTeam

The SupportTeam query returns information about activity within a support team. You may use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration

The API account must have the permission Allow Access to Support Session Reports and Recordings.

Parameters for SupportTeam

start_date=[YYYY-MM-DD]Specifies that the report should return team activity that began on or after this date and that is within the duration specified below.
start_time=[timestamp]Specifies that the report should return team activity that began at or after this time and that is within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report should return team activity that ended on or after this date and that is within the duration specified below.
end_time=[timestamp]Specifies that the report should return team activity that ended at or after this time and that is within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration will represent days; if start_time or end_time is specified, duration will represent seconds.

Optional parameter for SupportTeam

team_id=[integer]The numeric ID of the team by which to filter results. Only the activity within the specified team will be returned. If this parameter is not specified, results from all teams will be returned. To get a team's ID, see get_support_teams .

XML response for SupportTeam query

<team_activity_list>Contains a <team_activity> element for each team with any activity within the given parameters. If no teams are returned, this element will contain no <team_activity> elements. If an error occurs during the search, it will contain an <error> element describing the problem.

Also contains <start_time> and <end_time> elements displaying the time parameters in the system time and with a timestamp attribute in UTC.

Element names and attributes

/team_activity_list/team_activity
id (attribute)Integer representing the team’s unique ID.
name (attribute)The display name of the support team. Note that this field contains the team name as it currently appears, which may not match the value at the time of the conference if the team name has been subsequently changed.
<logged_in_representatives>Contains a <representative> element for each representative in that team who was logged into the representative console before the first event in the report occurred. If no representatives were logged in at the start time, this element will be empty.
<events>Contains an <event> element for each event that occurred within this team.
/team_activity_list/team_activity/logged_in_representatives/representative
gsnumber (attribute)Uniquely identifies the representative in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber is assigned on a per-connection basis, so if a representative leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same.

However, if the representative’s connection is terminated for any reason, when that representative logs back into the B Series Appliance, they will be assigned a new gsnumber.

A gsnumber may be recycled, so while two people connected at the same time will never have the same gsnumber, one person may have a gsnumber that was assigned to another person in the past. Can be used to correlate a <representative> element with an event’s <performed_by> or <destination> element.
id (attribute)Unique ID assigned to the representative.
<display_name>This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <private_display_name>.
<public_display_name>The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed.
<private_display_name>The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed.
<public_ip>The representative’s public IP address.
<private_ip>The representative’s private IP address.
/team_activity_list/team_activity/events/event
timestamp (attribute) The system time at which the event occurred.
event_type (attribute)

The type of event which occurred. Event types include the following:

Chat Message Pinned Session Moved Away from Queue
Conference Member Added Pinned Session Moved to Queue
Conference Member Departed Pinned Session Password Modified
Conference Member State Changed Representative Monitoring Started
Conference Owner Changed Representative Monitoring Stopped
File Download Session Pinned to Queue
File Download Failed Session Transferred Away from Queue
File Upload Session Transferred to Queue
File Upload Failed Session Unpinned from Queue
Files Shared  
<performed_by> The entity that performed the action. Indicates the entity’s gsnumber and also its type, indicating whether this entity was the system or a representative.
<destinations> If this event was targeted to one or more specific representatives, it will contain one or more <destination> elements as described below.
<files> If this event involved the transferring of files, then this element will contain a <file> element for every file transferred.
<data>

Contains an arbitrary number of <value name="_" value=" _" /> elements. The name and number of these elements varies based on the event_type. For example, when a representative logs into the representative console, a Conference Member Added event would contain <value> elements for the hostname, name, os, private_ip, public_ip, support_teams and user_id.

The XML data returned for the value of the element named support_teams includes an extra ; delimiter at the beginning of the data stream.
<body> The text of the chat message as displayed in the chat log area.
<encoded_body> Can be shown in place of the <body> element above. Contains the base64 (RFC 2045 section 6.8) encoded value of what would have been shown in the <body> element, and is shown ONLY if the <body> text contains characters that are invalid according to XML specification. These characters are typically the result of binary data being sent through chat messages.
/team_activity_list/team_activity/events/event/destinations/destination
gsnumber (attribute)Indicates the gsnumber of the entity to which the event was destined.
[value]The name of the entity to which the event was destined.
/team_activity_list/team_activity/events/event/files/file
name (attribute)The name of the transferred file.
size (attribute)An integer indicating the size of the transferred file.

Query examples for SupportTeam

  • Activity started November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportTeam&start_date=2024-11-01&duration=0
  • Activity started the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportTeam&start_date=2024-11-01&duration=31
  • Activity started 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportTeam&start_time=1730448000&duration=0
  • Activity started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportTeam&start_time=1730448000&duration=36000
  • Activity started November 1 2024 to present for a specific team
https://support.example.com/api/reporting?generate_report=SupportTeam&start_date=2024-11-01&duration=0&team_id=1
  • Activity ended November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportTeam&end_date=2024-11-01&duration=0
  • Activity ended the month of November 2024
https://support.example.com/api/reporting?generate_report=SupportTeam&end_date=2024-11-01&duration=31
  • Activity ended 8:00 AM November 1 2024 to present
https://support.example.com/api/reporting?generate_report=SupportTeam&end_time=1730448000&duration=0
  • Activity ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://support.example.com/api/reporting?generate_report=SupportTeam&end_time=1730448000&duration=36000
  • Activity ended November 1 2024 to present for a specific team
https://support.example.com/api/reporting?generate_report=SupportTeam&end_date=2024-11-01&duration=0&team_id=1

Syslog

The Syslog query downloads a ZIP file containing all Syslog files available on the appliance. Syslog files include all changes made on the /login administrative interface within the last 30 days.

Query example for syslog

https://access.example.com/api/reporting?generate_report=Syslog

VaultAccountActivity

The VaultAccountActivity query returns full information for all Vault account activity events that match given search parameters. You can use any of the following sets of parameters to generate reports:

  • start_date and duration
  • start_time and duration
  • end_date and duration
  • end_time and duration

The API account must have the permission Allow Access to Vault Account Activity Reports.

Parameters for VaultAccountActivity

start_date=[YYYY-MM-DD]Specifies that the report returns all events that happened on or after this date and that are within the duration specified below.
start_time=[timestamp]Specifies that the report returns all sessions, those still in progress, that began at or after this time as well as that are within the duration specified below. The time must be a UNIX timestamp (UTC).
end_date=[YYYY-MM-DD]Specifies that the report returns only closed sessions that ended on or after this date and that are within the duration specified below.
end_time=[timestamp]Specifies that the report returns only closed sessions that ended at or after this time and that are within the duration specified below. The time must be a UNIX timestamp (UTC).
duration=[integer]Length of time from the specified date or time for which you wish to pull reports, or 0 to pull from the specified date to present. If start_date or end_date is specified, duration represents days; if start_time or end_time is specified, duration represents seconds.

Optional parameter for VaultAccountActivity

limit=[string]

The category by which to filter results. Can be one of the following:

all Returns all results.
rep:[id] Returns sessions owned by a representative, specified by user ID. To get a representative's ID, see get_logged_in_reps.
account: [id] Returns all events involving a specific account.

XML response for VaultAccountActivity query

<vault_account_activity_list>Contains a <vault_account_activity> element for each event that matches the given criteria. If no events are returned, this element contains no <vault_account_activity> elements. If an error occurs during the search, it contains an <error> element describing the problem.

Element names and attributes

timestamp (attribute)The system time at which the event occurred.
AccountThe ID of the Vault account.
event_type (attribute)The type of event which occurred. Event types include the following:
Account Created
Account Deleted
Credentials Checked Out
Credentials Checked In
Password Changed
Password Rotation Failed
Credentials Used
Credentials Force Checked In
<performed_by>The entity that performed the action. Indicates the entity’s ID and also its type, indicating whether this action was performed by the system, a representative, or an API account.
<data>The value of this attribute depends on the event_type. For a Password Changed event, it contains values like Manually Edited, Manually Rotated, or Rotate after check in. For a Password Rotation Failed event, it contains an error string explaining the reason for its failure. For a Credential Checked Out event, if the credentials were used in a session, then it contains the LSID of the session.

Updated 5 days ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.