PagerDuty Blog

Hack Your On-Call Status with PagerDuty's API

Knowing your on-call status is more important than knowing if it’s raining outside. Unlike dealing with the drizzle that’s passed over San Francisco recently, if I’m on-call you need leave the house with more than an umbrella.

Your on-call status is an integral part of PagerDuty’s iOS and Android apps. We’ve also created a few new endpoints on our REST API that make getting your current on-call status more straightforward. Full documentation of these new endpoints, as always, is on our developer documentation site.

To stayed informed of my current on-call status, I’ve hammered out a couple shell script one-liners and a JavaScript bookmarklet. You will need a PagerDuty API key to try the scripts out. These were written for a Mac OS X environment with node installed, but can be easily modified to run in other environments.

Send an Inspiration Email Reminder

Sometimes it’s useful to treat an escalation policy as a mailing list. For a particularly rough on-call rotation, this script will send an inspirational email to everyone on-call for a particular escalation policy. Animal videos are always appreciated.

A Pleasant Voice Reminder


When you have over 50 tabs open in Chrome, more text on the screen is the last thing you need. I’ve created an alias of this script so when I type “amioncall” in the terminal Mac OS X will speak my on-call status in a pleasant voice.

Bookmarklet for your Toolbar


I have on-call handoff notifications configured for all of my accounts, but sometimes it’s useful to know how long you have left until your shift ends. I wrote a tiny JavaScript bookmarklet that’s in my toolbar that pops up my on-call status on any page.

Hooking it All Up!

# Send an inspirational email to people on-call for an escalation policy.
# Node required, tested on Mac OS X.
ESCALATION_POLICY_ID=<enter id> ACCOUNT=<enter account> API_TOKEN=<enter token> && curl –silent -H "Authorization: Token token=${API_TOKEN}" "https://${ACCOUNT}${ESCALATION_POLICY_ID}/on_call" | xargs -0 node -e "console.log('mailto:' + JSON.parse(process.argv[1]) { return }).join(',') + '?subject=\"Keep calm and carry on.\"')" | xargs open

// Create an on-call overlay with a user's on-call status.
// Designed to be used as a bookmarklet.
(function() {
var el = null, d = document, id = "pd-widget";
var account = "", apiKey = "", userId = "";
function createWidget() {
el = d.createElement("table");
el.setAttribute("id", id);
el.setAttribute("style","position:fixed;top:20px;right:20px;padding:20px;background:#fff;font:12px/20px monospace;z-index:99999;max-height:100%;overflow:auto;border-radius:10px;border:2px solid #000");
el.innerHTML = "<p>Loading…</p>";"block";
function render(onCall) {
var widget = document.getElementById(id);
var onCallHTML = "<h3>When am I off-call?</h3>";
onCall.forEach(function(oc) {
onCallHTML += "<p>" + + " (level " + oc.level + "): " + ((oc.end && new Date(oc.end)) || "never") + "</p>";
widget.innerHTML = onCallHTML;
function fetch() {
var request = new XMLHttpRequest();"GET", "https://" + account + "" + userId + "/on_call" , true);
request.setRequestHeader("Authorization", "Token token=" + apiKey);
request.onreadystatechange = function() {
var done = 4, ok = 200, json = "";
if (request.readyState == done && request.status == ok) {
if (request.responseText) {
json = JSON.parse(request.responseText);

view raw
hosted with ❤ by GitHub

# Have Mac OS X 'speak' your on-call status
# Node required.
USER_ID=<enter id> ACCOUNT=<enter account> API_TOKEN=<enter token> && curl –silent -H "Authorization: Token token=${API_TOKEN}" "https://${ACCOUNT}${USER_ID}/on_call" | xargs -0 node -e "if(JSON.parse(process.argv[1]).user.on_call.length > 0) { console.log('You are on-call') } else { console.log('You are off-call.') }" | xargs say

view raw
hosted with ❤ by GitHub