Events

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

Note

Starting with Illumio Core 18.2, use this Events API instead of Audit Events.

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 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 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
`href`	Unique href for this event, which can be used for event lookup via the events API	String
`org_id`	org_id for this event.	Integer
`version`	The event version of this event for the category it falls under	Sring
`event_id`	Unique request/transaction identifier of the API request / context from which this event was generated	String
`event_type`	Event name that clearly describes the event	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`	This event's level of importance	String
`timestamp`	RFC 3339 timestamp at which this event was originally created	String
`pce_fqdn`	Fully qualified domain name of the PCE, where this event originated	Sring
`created_by`	The entity responsible for the creation of this event	String

Properties

Property	Description	Type
`href`	Unique href for this event, which can be used for event lookup via the events API	String
`org_id`	org_id for this event.	Integer
`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, which can be harvested for reporting and measuring throughput; for example, a user pairing or unpairing workloads in the PCE web console.	String
`timestamp`	RFC 3339 timestamp at which this event was originally created	Hash
`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

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"
          }
        }
      }
    ]
  }
]

REST APIs for 22.5