Reporting API
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 reports of the /login administrative interface.
XML data is pulled by sending a simple HTTP request to the B Series Appliance. 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.
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://access.example.com/api/reporting.
An XML schema which formally describes the format of the returned reporting data is available at https://access.example.com/api/reporting.xsd.
Note
The reporting API is an authenticated API. The API account must have access to the reporting API.
For instructions on using authenticated APIs using OAuth, see Authenticate to the API.
Required parameter for reporting API
| generate_report=[string] |
The type of report to be generated. Report types can be any of the following:
|
The reporting API returns XML responses that declare a namespace. If you are parsing these responses with a namespace-aware parser, you must 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.
AccessSession
The AccessSession 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
Parameters for AccessSession
| 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. |
XML response for AccessSession 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 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. 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. 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. |
| <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. |
| <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. |
| <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 and only if the user initiated screen sharing during the session. It is available only for sessions that have successfully ended. |
| <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 user initiated screen sharing during the session. It is available only for sessions that have successfully ended. |
| <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 user 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 remote endpoint accessed by the user. |
| <primary_rep> | Lists the gsnumber and id as attributes and as an element, the name of the user who owned the session. |
| <customer_list> | A list of all endpoints accessed in the session. There should always be exactly one endpoint per session in the current BeyondTrust API version. The format of each <customer> element is described below. |
| <rep_list> | A list of all users who participated in the session, whether as the session owner or as conference members. The format of each <representative> element is described below. |
| <session_details> | Contains a chronological list of all events which occurred during the session. This element contains one or more child <event> elements, described below. |
/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/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 endpoint in regards to its current connection to the BeyondTrust Appliance B Series. A gsnumber may be recycled, so while two endpoints connected at the same time will never have the same gsnumber, one endpoint may have a gsnumber that was assigned to another endpoint in the past. Can be used to correlate a <customer> element with a <primary_customer> or with an event's <performed_by> or <destination> element. |
| <username> | The name used to identify the endpoint during the session. |
| <public_ip> | The endpoint's public IP address. |
| <private_ip> | The endpoint's private IP address. |
| <hostname> | The hostname of the endpoint. |
| <os> | The operating system of the endpoint. |
/session_list/session/rep_list/representative
| gsnumber (attribute) | Uniquely identifies the user in regards to their current connection to the BeyondTrust Appliance B Series. A gsnumber is assigned on a per-connection basis, so if a user leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same. However, if the user's connection is terminated for any reason, when that user 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 element with a <primary_rep> or with an event's <performed_by> or <destination> element. |
| id (attribute) | Unique ID assigned to the user. |
| <username> | The username assigned to the user. |
| <display_name> | The display name assigned to the user. Note that this field contains the display name's value at the time of the conference, which may not match the current value if the display_name has subsequently been changed. |
| <public_ip> | The user's public IP address. |
| <private_ip> | The user's private IP address. |
| <hostname> | The hostname of the user's computer. |
| <os> | The operating system of the user's computer. |
| <session_owner> | Integer value (1 or 0) indicating whether the user was the owner of the session or was merely a conference member. |
| <seconds_involved> | Integer value indicating the number of seconds the user was involved in this session. |
| <invited> | Integer value (1) present only if the user is an invited user. |
/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:
*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 endpoint, 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 user. | ||||||||||||||||||||||||||||||||
| <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. | ||||||||||||||||||||||||||||||||
| <files> | If this event involved the transferring of files, then this element will contain a <file> element for every file transferred. | ||||||||||||||||||||||||||||||||
| <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 user. This is to prevent overload with the large amount of dynamic data that can be retrieved from the remote system. |
||||||||||||||||||||||||||||||||
| <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 user joins the session, a Conference Member Added event would contain <value> elements for the user's name, private_ip, public_ip, hostname, and os. |
/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 endpoint 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 AccessSession
- Sessions started November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSession&start_date=2024-11-01&duration=0
- Sessions started the month of November 2024
https://access.example.com/api/reporting?generate_report=AccessSession&start_date=2024-11-01&duration=30
Sessions started 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSession&start_time=1730448000&duration=0
- Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSession&start_time=1730448000&duration=36000
- Sessions ended November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSession&end_date=2024-11-01&duration=0
- Sessions ended the month of November 2024
https://access.example.com/api/reporting?generate_report=AccessSession&end_date=2024-11-01&duration=30
- Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSession&end_time=1730448000&duration=36000
- Session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/reporting?generate_report=AccessSession&lsid=c69a8e10bea9428f816cfababe9815fe
- Sessions c69a8e10bea9428f816cfababe9815fe, a5eeaa58591047b88556f944804227b0, 5bf07601298b495b87310da9ce571e22
https://access.example.com/api/reporting?generate_report=AccessSession&lsids=c69a8e10bea9428f816cfababe9815fe,a5eeaa58591047b88556f944804227b0,5bf07601298b495b87310da9ce571e22
AccessSessionListing
The AccessSessionListing 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
Parameters for AccessSessionListing
| 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 represents days; if start_time or end_time is specified, duration represents seconds. |
XML response for AccessSessionListing 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
| lsid (attribute) | The session ID for the given session. |
| 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 customer relationship management ticket ID. This can be input from within the access console or defined programmatically. This element is displayed only if an external key has been defined. |
Query examples for AccessSessionListing
- Sessions started November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionListing&start_date=2024-11-01&duration=0
- Sessions started the month of November 2024
https://access.example.com/api/reporting?generate_report=AccessSessionListing&start_date=2024-11-01&duration=30
- Sessions started 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionListing&start_time=1730448000&duration=0
- Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSessionListing&start_time=1730448000&duration=36000
- Sessions ended November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionListing&end_date=2024-11-01&duration=0
- Sessions ended the month of November 2024
https://access.example.com/api/reporting?generate_report=AccessSessionListing&end_date=2024-11-01&duration=30
- Sessions ended 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionListing&end_time=1730448000&duration=0
- Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSessionListing&end_time=1730448000&duration=36000
AccessSessionRecording
The AccessSessionRecording query returns the requested access session recording file. Depending on your browser, this query will either immediately begin download or prompt you to open or save the file. Note that the requesting user must have permission to view session recordings.
Parameter for AccessSessionRecording
| lsid=[string] | The session ID for which you wish to download the video recording of the session. |
Query example for AccessSessionRecording
- AccessSessionRecording: Session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/reporting?generate_report=AccessSessionRecording&lsid=c69a8e10bea9428f816cfababe9815fe
AccessSessionSummary
The AccessSessionSummary query returns an overview of access session statistics by user. 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
Parameters for AccessSessionSummary
| 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 represents days; if start_time or end_time is specified, duration represents seconds. |
| report_type=[string] | In the current BeyondTrust API version, user is the only accepted value. |
XML response for AccessSessionSummary 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
| id (attribute) | Returns the user's unique ID. |
| type (attribute) | Specifies the report type generated. This value is always user in the current API version. |
| <display_name> | The display name of the user. 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 user, which may have been edited since the time of the first returned session. |
| <total_sessions> | The total number of sessions run by the user in the time specified. |
| <avg_sessions_per_weekday> | The average number of sessions conducted on Monday through Friday by the user, expressed as a decimal rounded to the nearest point. |
| <avg_duration> | The average length of each session, expressed as HH:MM:SS. |
Query examples
- Sessions started November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&start_date=2024-11-01&duration=0&report_type=user
- Sessions started the month of November 2024, by user
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&start_date=2024-11-01&duration=30&report_type=user
- Sessions started 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&start_time=1730448000&duration=0&report_type=user
- Sessions started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&start_time=1730448000&duration=36000&report_type=user
- Sessions ended November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&end_date=2024-11-01&duration=0&report_type=user
- Sessions ended the month of November 2024
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&end_date=2024-11-01&duration=30&report_type=user
- Sessions ended 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&end_time=1730448000&duration=0&report_type=user
- Sessions ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=AccessSessionSummary&end_time=1730448000&duration=36000&report_type=user
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. Note that the requesting user must have permission to view session 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 AccessSession report. |
Optional parameter for CommandShellRecording
| format=[string] | If this parameter has the value of txt, the command shell output will be in a text format instead of a recording. |
Query examples for CommandShellRecording
- CommandShellRecording: First shell instance of session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/reporting?generate_report=CommandShellRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=0
- CommandShellRecording: Third shell instance of session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/reporting?generate_report=CommandShellRecording&lsid=c69a8e10bea9428f816cfababe9815fe&instance=2
EndpointLicenseUsage
The EndpointLicenseUsage query downloads a ZIP file containing detailed information (English only) on your BeyondTrust license usage. This file contains a list of all Jump Items (not counting uninstalled Jump Clients), daily counts for Jump Item operations and license usage, and a summary for the BeyondTrust Appliance B Series and its endpoint license usage and churn.
Query example for EndpointLicenseUsage
- EndpointLicenseUsage
https://access.example.com/api/reporting?generate_report=EndpointLicenseUsage
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
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 element describing the problem. |
Element names and attributes
| 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. |
Query examples for JumpItem
- Events started November 1 2024 to present
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0
- Events started the month of November 2024
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=30
Events started 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=JumpItem&start_time=1730448000&duration=0
- Events started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=JumpItem&start_time=1730448000&duration=36000
- Events started November 1 2024 to present for a specific Jump Group
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0&jump_group='personal:1'
- Events started November 1 2024 to present for a specific Jump Item
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0&jump_item=1:jump_client
- Events started November 1 2024 to present for a specific actor
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0&performed_by='user:1'
- Events started November 1 2024 to present for a specific Jump Group and for a specific actor
https://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=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://access.example.com/api/reporting?generate_report=JumpItem&start_date=2024-11-01&duration=0&jump_item=1:local_rdp&performed_by='system'
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>
Team
The Team query returns information about activity within a 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
Parameters for Team
| 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 Team
| 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. |
XML response for Team 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 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_privileged users> | Contains a element for each user in that team who was logged into the access console before the first event in the report occurred. If no users were logged in at the start time, this element will be empty. |
| Contains an element for each event that occurred within this team. |
/team_activity_list/team_activity/logged_in_representatives/representative
| gsnumber (attribute) | Uniquely identifies the user in regards to their current connection to the B Series Appliance. A gsnumber is assigned on a per-connection basis, so if a user leaves a session and then rejoins without logging out of the B Series Appliance, their gsnumber will remain the same. However, if the user's connection is terminated for any reason, when that user 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 element with an event's <performed_by> or <destination> element. |
| id (attribute) | Unique ID assigned to the user. |
| <display_name> | The display name assigned to the user. Note that this field contains the display name's value at the time of the conference, which may not match the current value if the display_name has subsequently been changed. |
| <public_ip> | The user's public IP address. |
| <private_ip> | The user'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:
|
||||||||||||||||||
| <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 user. | ||||||||||||||||||
| <destinations> | If this event was targeted to one or more specific users, it will contain one or more <destination> elements as described below. | ||||||||||||||||||
| <files> | If this event involved the transfer 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 user logs into the access console, a Conference Member State Changed event would contain <value> elements for the hostname, os, private_ip, public_ip, and state. |
||||||||||||||||||
| <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. |
| type (attribute) | Indicates whether this entity was the system or a user. |
| [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 Team
- Activity started November 1 2024 to present
https://access.example.com/api/reporting?generate_report=Team&start_date=2024-11-01&duration=0
- Activity started the month of November 2024
https://access.example.com/api/reporting?generate_report=Team&start_date=2024-11-01&duration=30
- Activity started 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=Team&start_time=1730448000&duration=0
- Activity started 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=Team&start_time=1730448000&duration=36000
- Activity started November 1 2024 to present for a specific team
https://access.example.com/api/reporting?generate_report=Team&start_date=2024-11-01&duration=0&team_id=1
- Activity ended November 1 2024 to present
https://access.example.com/api/reporting?generate_report=Team&end_date=2024-11-01&duration=0
- Activity ended the month of November 2024
https://access.example.com/api/reporting?generate_report=Team&end_date=2024-11-01&duration=30
- Activity ended 8:00 AM November 1 2024 to present
https://access.example.com/api/reporting?generate_report=Team&end_time=1730448000&duration=0
- Activity ended 8:00 AM November 1 2024 to 6:00 PM November 1 2024
https://access.example.com/api/reporting?generate_report=Team&end_time=1730448000&duration=36000
- Activity ended November 1 2024 to present for a specific team
<https://access.example.com/api/reporting?generate_report=Team&end_date=2024-11-01&duration=0&team_id=1>
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
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, as well as 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 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:
|
Note
For more information on getting a representative's ID, please see get_logged_in_reps.
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 element describing the problem. |
Element names and attributes
| timestamp (attribute) | The system time at which the event occurred. |
| Account | The 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. |
| 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 about 1 month ago