Events

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

Events include logging a user in or out of the PCE, granting a role to a user, pairing or unpairing a workload, 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 the Events Administration Guide.

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 an 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]

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ʼs 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. For types of events returned from a GET call, see the response properties table below.	String
status	Status of the event, either success or failure.	String
timestamp	Timestamp.	Hash
timestamp[gte]	Event start timestamp in RFC 3339 format.	String
timestamp[lte]	Event end timestamp in RFC 3339 format.	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, which can be harvested for reporting and measuring throughput; for example, a user pairing or unpairing workloads in the PCE web console.	String
max_results	Maximum number of events to return. The default is 100, and the maximum is 10000.	Integer

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"
      }
    },
    "event_type": "agent.clone_detected",
    "status": null,
    "severity": "info",
    "action": null,
    "resource_changes": [],
    "notifications": [
      {
        "uuid": "xxxxxxxx-4833-4975-bf9d-xxxxxxxxxxxx",
        "notification_type": "agent.clone_detected",
        "info": {
          "agent": {
            "href": "/orgs/1/agents/xxx",
            "name": null,
            "hostname": "xxx-xxxxx-xxxx"
          }
        }
      }
    ]
  }
]