Events

This Public Experimental API gets a collection of events or an individual event.

Note

Use this Events API instead of Audit Events.

Events include logging a user in or out of the PCE, granting a user a role, pairing or unpairing a workload, and creating a label, ruleset, or IP list.

Event Types

For a complete list of JSON events, descriptions, CEF/LEEF success events, and CEF/LEEF failure events, see List of Event Types

Event API Methods

Functionality	HTTP	URI
Get a collection of events.	`GET`	`[api_version][org_href]/events`
Get an individual event.	`GET`	`[api_version][event_href]`

Get Events

This API gets a collection of events or a specific event identified by an event ID (in the form of a UUID).

Get Events Collection

When getting a collection of events, be aware of the following caveats:

Use the max_results query parameter to increase the maximum number of events returned.
The largest value accepted for max_results is 10000. To return more than 10000 events, use Asynchronous GET Collection.

URI to Get a Collection of Events

GET [api_version][org_href]/events

URI to Get an Individual Event

GET [api_version][event_href]

Events Reference

This topic covers properties, parameters, and examples of events.

Parameters

Parameter	Description	Type
`xorg_id`	Organization ID in which the event occurred.	Integer
`created_by`	Information about the person, agent, or system that created the event. Created by system: `system`: Appears only if the event was generated by the PCE. Created by user properties: `href`: URI of the user who created the event. `username`: The user name (usually formatted as an e-mail address). Created by workload properties: `href`: URI of the agent on the workload that initiated the event. `hostname`: The hostname of the workload.	String
`event_type`	Type of the event specified by the `event_type` query parameter if given. If no query parameters are given, all event types are returned. See the response properties table below for types of events returned from a GET call.	String
`max_results`	Maximum number of events to return. The default is 100, and the maximum is 10000.	Integer
`severity`	Severity level of the events retrieved. Values include: Warning (`warning`): A warning that the event is likely to occur if action is not taken. Error (`err`) Information (`info`): Normal operational messages can be harvested for reporting and measuring throughput, such as user pairing or unpairing workloads in the PCE web console.	String
`status`	Status of the event, either `success` or `failure`.	String
`timestamp[gte]`	Event start timestamp in RFC 3339 format.	String
`timestamp[lte]`	Event end timestamp in RFC 3339 format.	String

Properties

Parameter	Description	Type
`event_type`	Type of the event specified by the `event_type` query parameter if given. If no query parameters are given, all event types are returned. See the response properties table below for types of events returned from a GET call.	String
`status`	Status of the event; usually a mapping of `api_status_code` to a generic result string; nil if no action. For presentation purposes only.	String
`severity`	Severity level of the events retrieved. Values include: Warning (`warning`): A warning that the event is likely to occur if action is not taken. Error (`err`) Information (`info`): Normal operational messages can be harvested for reporting and measuring throughput, such as user pairing or unpairing workloads in the PCE web console.	String
`created_by`	Information about the person, agent, or system that created the event. Created by system: `System` This appears only if the PCE generated the event. Created by user properties: `href`: URI of the user who created the event. `username`: The user name (usually formatted as an e-mail address). Created by workload properties: `href`: URI of the agent on the workload that initiated the event. `hostname`: The hostname of the workload.	String

Examples

Curl Command to Get an Event

You need the ID of the system event you want to get, which is the number at the end of its HREF path property: "/2/events/68632".

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/events/12345 -H "Accept: application/json" -u $KEY:$TOKEN

Curl Command Get Event Collection

In this example, only two events are returned because ofmax_events=2.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/events?max_results=2 -H "Accept: application/json" -u $KEY:$TOKEN

Example Response

[
  {
    "href": "/orgs/1/events/xxxxxxx-5f59-46ab-8f18-xxxxxxxxx",
    "timestamp": "2019-09-03T01:xx:xx.xxxZ",
    "pce_fqdn": "pce.my-company.com",
    "created_by": {
      "agent": {
        "href": "/orgs/1/agents/xxx",
        "hostname": "xxx-xxxxx-xxxx"
      }
    },
    "event_type": "agent.clone_detected",
    "status": null,
    "severity": "info",
    "action": null,
    "resource_changes": [],
    "notifications": [
      {
        "uuid": "xxxxxxx-e04b-43bc-a64a-xxxxxxxxxx",
        "notification_type": "agent.clone_detected",
        "info": {
          "agent": {
            "href": "/orgs/1/agents/xxx",
            "name": null,
            "hostname": "xxx-xxxxx-xxxx"
          }
        }
      }
    ]
  },
  {
    "href": "/orgs/1/events/xxxxxxx-60a2-4db4-b0f4-xxxxxxxxxx",
    "timestamp": "2019-09-03T0x:xx:xx.xxxZ",
    "pce_fqdn": "pce.my-company.com",
    "created_by": {
      "agent": {
        "href": "/orgs/1/agents/xxx",
        "hostname": "xxx-xxxxx-xxxx"
      }
    },
    ]
  }
]

REST APIs for 24.2.20 and 24.2.10