Caution

As of 2025-03-11, Grafana OnCall OSS has entered maintenance mode, and will be archived on 2026-03-24. No further feature development will occur; however, we will still provide fixes for critical bugs and for valid CVEs with a CVSS score of 7.0 or higher. For more information, refer to our blog post.

Documentationbreadcrumb arrow OnCallbreadcrumb arrow API referencebreadcrumb arrow OnCall shifts HTTP API
Open source

OnCall shifts HTTP API

Create an OnCall shift

Required permission: grafana-oncall-app.schedules:write

shell 
curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "Demo single event",
      "type": "single_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T08:00:00",
      "duration": 10800,
      "users": [
          "U4DNY931HHJS5"
      ]
  }'

The above command returns JSON structured in the following way:

JSON 
{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}
ParameterUniqueRequiredDescription
nameYesYesOn-call shift name.
typeNoYesOne of: single_event, recurrent_event, rolling_users.
team_idNoID of the team.
time_zoneNoOptionalOn-call shift time zone. Default is local schedule time zone. This field will override the schedule time zone if changed. For more information refer to time zones.
levelNoOptionalPriority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex.
startNoYesStart time of the on-call shift. This parameter takes a date format as yyyy-MM-dd'T'HH:mm:ss (for example “2020-09-05T08:00:00”).
durationNoYesDuration of the event.
frequencyNoIf type = recurrent_event or rolling_usersOne of: hourly, daily, weekly, monthly.
intervalNoOptionalThis parameter takes a positive integer that represents the intervals that the recurrence rule repeats. If frequency is set, the default assumed value for this will be 1.
untilNoOptionalWhen the recurrence rule ends (endless if None). This parameter takes a date format as yyyy-MM-dd'T'HH:mm:ss (for example “2020-09-05T08:00:00”).
week_startNoOptionalStart day of the week in iCal format. One of: SU (Sunday), MO (Monday), TU (Tuesday), WE (Wednesday), TH (Thursday), FR (Friday), SA (Saturday). Default: SU.
by_dayNoOptionalList of days in iCal format. Valid values are: SU, MO, TU, WE, TH, FR, SA.
by_monthNoOptionalList of months. Valid values are 1 to 12.
by_monthdayNoOptionalList of days of the month. Valid values are 1 to 31 or -31 to -1.
usersNoOptionalList of on-call users.
rolling_usersNoOptionalList of lists with on-call users (for rolling_users event type). Grafana OnCall will iterate over lists of users for every time frame specified in frequency. For example: there are two lists of users in rolling_users : [[Alex, Bob], [Alice]] and frequency = daily . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on.
start_rotation_from_user_indexNoOptionalIndex of the list of users in rolling_users, from which on-call rotation starts. By default, the start index is 0

For more information about recurrence rules, refer to RFC 5545.

HTTP request

POST {{API_URL}}/api/v1/on_call_shifts/

Get OnCall shifts

Required permission: grafana-oncall-app.schedules:read

shell 
curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

JSON 
{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

List OnCall shifts

Required permission: grafana-oncall-app.schedules:read

shell 
curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

JSON 
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "OH3V5FYQEYJ6M",
      "name": "Demo single event",
      "type": "single_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T08:00:00",
      "duration": 10800,
      "users": ["U4DNY931HHJS5"]
    },
    {
      "id": "O9WTH7CKM3KZW",
      "name": "Demo recurrent event",
      "type": "recurrent_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T16:00:00",
      "duration": 10800,
      "frequency": "weekly",
      "interval": 2,
      "week_start": "SU",
      "by_day": ["MO", "WE", "FR"],
      "by_month": null,
      "by_monthday": null,
      "users": ["U4DNY931HHJS5"]
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

Note: The response is paginated. You may need to make multiple requests to get all records.

The following available filter parameters should be provided as GET arguments:

  • name (Exact match)
  • schedule_id (Exact match)

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/

Update OnCall shift

Required permission: grafana-oncall-app.schedules:write

shell 
curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Demo single event",
    "type": "single_event",
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
  }'

The above command returns JSON structured in the following way:

JSON 
{
  "id": "OH3V5FYQEYJ6M",
  "name": "Demo single event",
  "type": "single_event",
  "team_id": null,
  "time_zone": null,
  "level": 0,
  "start": "2020-09-10T08:00:00",
  "duration": 10800,
  "users": ["U4DNY931HHJS5"]
}

HTTP request

PUT {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

Delete OnCall shift

Required permission: grafana-oncall-app.schedules:write

shell 
curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/