Retrieve Trigger Event Data Using the API

The original details of any event sent from your monitoring tools to PagerDuty can be retrieved through the REST API. This process requires the use of our Log Entries API with channels included, which will expose the original data (be it an email or an Events API request body) received through the integration.

Introduction

As noted on our Log Entries API page:

PagerDuty keeps a log of all the events that happen to an incident. These are exposed as log entries. Log entries give you more insight into how your team or organization is handling your incidents.

Log entry data includes details about the event(s) that affected the incident throughout its lifecycle, such as:

  • the data contained in events sent by the integration
  • what users were notified and when
  • how they were notified
  • what user(s) acknowledged or resolved the incident
  • any automatic actions that occurred to the incident
  • other manual user actions, such as a reassignment or a note

To obtain the event data sent through the integration, we'll be retrieving a specific type of log entry called the trigger log entry. For this, you will need the ID (a string of alphanumeric characters that starts with P) or the number of the incident that the event triggered. There are then two ways of obtaining trigger log entries:
With just the incident number:
You can obtain the first trigger log entry (which initially triggered the incident) in just two API calls.
With the incident ID:
You can obtain all trigger log entries in one or more API calls.

The channel property of log entries

In both cases we will append channels to the array-type URL parameter include[] when obtaining log entries. Each log entry object returned will then contain a channel property. This property will itself contain an object with the triggering event metadata. Note the following about this property:

  • The structure of the object in the channel property will vary, but it will always contain a property named type.
  • For trigger log entries, the type property will be api, email or web_trigger.
  • The overall structure of the channel object depends on which of these three it is:
    api
    It will contain the other properties of the event that was received through the integration
    email
    It will contain aptly-named properties subject, body, from and to, in addition to a property summary containing the short event description extracted from the email per management rules (if nothing, this will be the subject header of the email).
    web_trigger
    Will contain subject (short description / incident title), details (long description) and summary (usually the same as

Disclaimer:

the description of the structure of the log_entry.channel produced here only reflects what it was observed to be as of this writing. A full specification of the log_entry.channel property's schema has not yet been published in our API Reference because it may be subject to change until a permanent structure is decided upon.

Obtaining the first trigger log entry with the incident number

Given the incident number, you can get the ID/endpoint of the trigger log entry and then obtain its details, as follows:

  1. Use a GET request to the endpoint /incidents/{id} (where {id} could be an ID or incident number) to obtain the incident object, and note the following:
  2. In the response, the property incident.first_trigger_log_entry will contain a LogEntryReference object pointing to the log entry.
  3. The LogEntryReference object has a property self containing the full API URL to the log entry. Alternately, the id property has the ID of the log entry, which can be used to construct the endpoint URL.
  4. Alternately, one can obtain the incident ID from the incident.id property in the response, and then switch to using the second method.
  5. Make a GET request to the endpoint /log_entries/{id} and include channels by appending channels to the include[] list parameter. For instance, if the log entry ID is R2FREAAI4XXAGD6L458SRJ9BK1, the full URL would be:
    https://api.pagerduty.com/log_entries/R2FREAAI4XXAGD6L458SRJ9BK1?include%5B%5D=channels
  6. Finally, in the response, the channel property will contain the triggering event metadata.

Obtaining all trigger log entries using the incident ID

Given the incident ID, you can get the log entries for the incidents, iterate through them, skip the ones that aren't trigger log entries and examine/extract data from the ones that are:

Make a GET request to /incidents/{id}/log_entries, where {id} is the incident's ID, and include channels. If the incident ID is PQK2LJ3, the full URL will look like the following:
https://api.pagerduty.com/incidents/PQK2LJ3/log_entries?include%5B%5D=channels

Obtain the list of the log entries from the log_entries property in the response.

Note the more and total properties in the JSON-encoded object in the body (see Pagination):

  • If more is false, the current response contains all log entries, and you may proceed.
  • If more is true, in which total is greater than limit (the default, if unset, is 25):
  • You will need to perform additional API calls to fetch, incrementing offset by the value of limit each -
    time (the starting value, if unspecified, is zero) until the observed value of more is false.
  • The total number of API calls to get log entries will be n/p+1 where n is the total number of log entries, p is the page size (per the limit parameter), and n/p represents integer division.
  • Tip: set the limit parameter to 100 for better performance. This will reduce the overall number of required API calls.

Once you have the full list of incident log entries, iterate through them and select/take action on them as desired:

  • Each list item, a log entry, should contain a type property. This property will be trigger_log_entry for the log entry species that we are after.
  • The items in the list are sorted in reverse chronological order, i.e. with newest events at the beginning. In each case, the created_at property will give the timestamp of the log entry as a DateTime (ISO 8601) formatted string.
  • The channel property will contain the trigger event metadata.

Retrieve Trigger Event Data Using the API