PagerDuty Schedules API

Introduction

The PagerDuty Schedules API allows for RESTful interaction with PagerDuty schedules. Currently, only the schedule entries API is available, which lets you see who is on-call at any given time, or lets you query for all of the schedule “entries” or on-call shifts over a given date range.

Getting Started

The schedule entries query API can be used to determine who is oncall on any given Schedule in PagerDuty. If you don’t already have any schedules in PagerDuty, you can create one:

  1. In your account, under the On-Call Schedules tab, click the “Create New Schedule” button in the top right corner.
  2. Go through the steps to create the on-call schedule you want, and hit “Create Schedule”.
  3. Take note of your schedule ID. The URL for this new schedule will contain the schedule ID: 
    http://<your_subdomain>.pagerduty.com/schedule/rotations/<schedule_id>

Making a Request

To make a schedule entries query API request, perform a GET on the following URL:

https://<your_subdomain>.pagerduty.com/api/v1/schedules/<schedule_id>/entries[?params]

So, for instance, if your PagerDuty subdomain is acme, your schedule’s ID is P4MHU96 and your query params are since=2011-06-01&until=2011-06-20 (query parameters are described in detail below), then the API request would be:

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01&until=2011-06-20

Response values are in JSON and are detailed in later sections.

Authentication

Our REST APIs currently use HTTP basic access authentication. You can add the username/password pair in your API request header.

Below is an example of testing HTTP basic auth with curl, assuming the subdomain ‘acme’, username ‘john@acme.com’, and password ‘myPassw0rd’:

 curl --basic --user "john@acme.com:myPassw0rd" "http://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01&until=2011-06-20"

If you’re testing with curl, remember to include quotation marks.

Parameters

This section details all of the valid query parameters available with the schedule entries query API.

Date Range – since and until

These two parameters are mandatory for all schedule entry queries. They define the date range over which you want to return on-call schedule entries. The maximum range queryable at once is three months.

Example dates in ISO 8601 format:

May 6th, 2011 at 5pm UTC: 2011-05-06T17:00Z
May 6th, 2011 at 3:30am PDT: 2011-05-06T03:30-07
May 6th, 2011 at midnight (time is optional): 2011-05-06

Shift Truncation and overflow

The on-call schedule entries returned will not pass the bounds of the date range passed, as defined by the since and until parameters.

Any on-call schedule entries that pass the date range bounds will be truncated at the bounds themselves, unless the parameter overflow=true is passed. This parameter defaults to false.

For instance, if your schedule is a rotation that changes daily at midnight UTC, and your date range is from 2011-06-01T10:00:00Z to 2011-06-01T14:00:00Z:

User Filtering – user_id

To filter the returned on-call schedule entries by a specific user, you can optionally add the user_id parameter to the query. Please see below for more info on how to find your users’ IDs. OPTIONAL

Aside: How to find your User or Schedule IDs

To use the user_id filter above, you need to provide a user’s ID. PagerDuty IDs are 7-character alphanumeric strings that begin with the letter ‘P’. You can find these IDs in one of two places:

  1. You can find your user IDs returned in your Schedule Entries Query API results. You can first perform a broader query (without any filters applied) manually, and look through the results to find the user IDs that you are interested in. Once found, your subsequent queries can use these IDs. The API response format is detailed later on in this document.
  2. You can also find your user IDs within PagerDuty’s website itself. For instance, under the ‘Users’ tab, click on the user that you are interested in filtering your query by. The URL for this user’s PagerDuty page will contain the user ID: 
    http://<subdomain>.pagerduty.com/users/<user_id>
    Schedule IDs can be found in a similar manner.

Output Fields & Restrictions – fields

fields: Used to restrict the properties of each on-call schedule entry returned to a set of pre-defined fields. If omitted, returned schedule entries have all fields present. OPTIONAL

Each returned schedule entry can have the following fields:

The echo parameter

echo: Is often used for out-of-order AJAX request management. As a convenience, any value passed here will be echoed back to the caller in the API response. OPTIONAL

Response Format

All responses are in JSON format. The response object looks like:


{
  total:<int>,
  entries:
  [
    {
      start:<date>,
      end:<date>,
      user: <user object>
    },
    <other schedule entries...>
  ]
}

Returned fields:

Examples

Below are some examples of Schedule Entries API requests.

In all examples, the (fake) PagerDuty account subdomain used is acme, the schedule’s ID is P4MHU96 and the current date is 2011-06-01.

Fetch the on-call schedule for the upcoming month.

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01&until=2011-07-01

Find out who is on-call at 2pm UTC today.

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01T14:00:00Z&until=2011-06-01T14:00:00Z

Find out who is on-call at 2pm UTC today, but include the start and end time of their entire shift.

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01T14:00:00Z&until=2011-06-01T14:00:00Z&overflow=true

Fetch all of the on-call shifts for user P62KJ18 over the upcoming month.

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01&until=2011-07-01&user_id=P62KJ18

Fetch all of the on-call shifts for user P62KJ18 over the upcoming month, but omit his user details in the results.

https://acme.pagerduty.com/api/v1/schedules/P4MHU96/entries?since=2011-06-01&until=2011-07-01&user_id=P62KJ18&fields=start,end

Errors

If the API request was successful, PagerDuty will respond to it with HTTP status code 200 and the schedule entries that match the query.

If the API request was unsuccessful, PagerDuty will respond with a corresponding HTTP error status code and the response body will contain PagerDuty error details.

The response body (with error details) will have the following properties:

{
  error:
  {
    message: "Error Message String",
    code: 2001,   /* PagerDuty Error Code */
    errors: ["human-readable error details", "more details" ]
  }
}

HTTP Responses

The HTTP response is what can be used to determine if the request was successful, and if not, if the request should be retried.

Code HTTP Definition Description
200 OK The request was successful.
400 Bad Request Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will not work.
500 Internal Server Error Internal error while processing request. Please try again.

PagerDuty Error Codes

In the case of an error, the PagerDuty error code can give further details on the nature of the error.

Code Message
2000 Internal Error
2001 Invalid Input Provided
2002 Arguments Caused Error
2003 Missing Arguments
2004 Invalid ‘since’ or ‘until’ Parameter Values
2005 Invalid Query Date Range
2006 Authentication Failed
2007 Account Not Found
2008 Account Locked
2009 Only HTTPS Allowed For This Call
3004 Unknown Schedule

In addition to a code and message, the return value will also include an array of human-readable reasons for the error in the errors field. These human-readable values, and even their format, are subject to change.

See Plans and Pricing
Powered by Olark