Grafana OnCall HTTP API reference on Grafana Labs

Alerts HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

List Alerts

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

The above command returns JSON structured in the following way:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "AA74DN7T4JQB6",
      "alert_group_id": "I68T24C13IFW1",
      "created_at": "2020-05-11T20:08:43Z",
      "payload": {
        "state": "alerting",
        "title": "[Alerting] Test notification",
        "ruleId": 0,
        "message": "Someone is testing the alert notification within Grafana.",
        "ruleUrl": "{{API_URL}}/",
        "ruleName": "Test notification",
        "evalMatches": [
          {
            "tags": null,
            "value": 100,
            "metric": "High value"
          },
          {
            "tags": null,
            "value": 200,
            "metric": "Higher Value"
          }
        ]
      }
    },
    {
      "id": "AR9SSYFKE2PV7",
      "alert_group_id": "I68T24C13IFW1",
      "created_at": "2020-05-11T20:07:54Z",
      "payload": {
        "state": "alerting",
        "title": "[Alerting] Test notification",
        "ruleId": 0,
        "message": "Someone is testing the alert notification within Grafana.",
        "ruleUrl": "{{API_URL}}/",
        "ruleName": "Test notification",
        "evalMatches": [
          {
            "tags": null,
            "value": 100,
            "metric": "High value"
          },
          {
            "tags": null,
            "value": 200,
            "metric": "Higher Value"
          }
        ]
      }
    },
    {
      "id": "AWJQSGEYYUFGH",
      "alert_group_id": "I68T24C13IFW1",
      "created_at": "2020-05-11T20:06:58Z",
      "payload": {
        "state": "alerting",
        "title": "[Alerting] Test notification",
        "ruleId": 0,
        "message": "Someone is testing the alert notification within Grafana.",
        "ruleUrl": "{{API_URL}}/",
        "ruleName": "Test notification",
        "evalMatches": [
          {
            "tags": null,
            "value": 100,
            "metric": "High value"
          },
          {
            "tags": null,
            "value": 200,
            "metric": "Higher Value"
          }
        ]
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

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

id
alert_group_id
search—string-based inclusion search by alert payload

HTTP request

GET {{API_URL}}/api/v1/alerts/

Escalation Chains HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create an escalation chain

curl "{{API_URL}}/api/v1/escalation_chains/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "example-chain"
  }'

The above command returns JSON structured in the following way:

{
  "id": "FWDL7M6N6I9HE",
  "name": "example-chain",
  "team_id": null
}

Parameter	Required	Description
name	yes	Name of the escalation chain
team_id	no	ID of the team

HTTP request

POST {{API_URL}}/api/v1/escalation_chains/

Get an escalation chain

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

The above command returns JSON structured in the following way:

{
  "id": "F5JU6KJET33FE",
  "name": "default",
  "team_id": null
}

HTTP request

GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/

List escalation chains

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

The above command returns JSON structured in the following way:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "F5JU6KJET33FE",
      "name": "default",
      "team_id": null
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

HTTP request

GET {{API_URL}}/api/v1/escalation_chains/

Delete an escalation chain

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

HTTP request

DELETE {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/

Escalation Policies HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create an escalation policy

curl "{{API_URL}}/api/v1/escalation_policies/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "escalation_chain_id": "F5JU6KJET33FE",
      "type": "wait",
      "duration": 60
  }'

The above command returns JSON structured in the following way:

{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 60
}

Parameter	Required	Description
`escalation_chain_id`	Yes	Each escalation policy is assigned to a specific escalation chain.
`position`	Optional	Escalation policies execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down in the list.
`type`	Yes	One of: `wait`, `notify_persons`, `notify_person_next_each_time`, `notify_on_call_from_schedule`, `notify_user_group`, `trigger_webhook`, `resolve`, `notify_whole_channel`, `notify_if_time_from_to`.
`important`	Optional	Default is `false`. Will assign “important” to personal notification rules if `true`. This can be used to distinguish alerts on which you want to be notified immediately by phone. Applicable for types `notify_persons`, `notify_team_members`, `notify_on_call_from_schedule`, and `notify_user_group`.
`duration`	If type = `wait`	The duration, in seconds, when type `wait` is chosen. Valid values are: `60`, `300`, `900`, `1800`, `3600`.
`action_to_trigger`	If type = `trigger_webhook`	ID of a webhook.
`group_to_notify`	If type = `notify_user_group`	ID of a `User Group`.
`persons_to_notify`	If type = `notify_persons`	List of user IDs.
`persons_to_notify_next_each_time`	If type = `notify_person_next_each_time`	List of user IDs.
`notify_on_call _from_schedule`	If type = `notify_on_call_from_schedule`	ID of a Schedule.
`notify_if_time_from`	If type = `notify_if_time_from_to`	UTC time represents the beginning of the time period, for example `09:00:00Z`.
`notify_if_time_to`	If type = `notify_if_time_from_to`	UTC time represents the end of the time period, for example `18:00:00Z`.
`team_to_notify`	If type = `notify_team_members`	ID of a team.

HTTP request

POST {{API_URL}}/api/v1/escalation_policies/

Get an escalation policy

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

The above command returns JSON structured in the following way:

{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 60
}

Update an escalation policy

curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "wait",
    "duration": 300,
  }'

The above command returns JSON structured in the following way:

{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 300
}

HTTP request

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

HTTP request

GET {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/

List escalation policies

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

The above command returns JSON structured in the following way:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "E3GA6SJETWWJS",
      "escalation_chain_id": "F5JU6KJET33FE",
      "position": 0,
      "type": "wait",
      "duration": 60
    },
    {
      "id": "E5JJTU52M5YM4",
      "escalation_chain_id": "F5JU6KJET33FE",
      "position": 1,
      "type": "notify_person_next_each_time",
      "persons_to_notify_next_each_time": ["U4DNY931HHJS5"]
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

The following available filter parameter should be provided as a GET argument:

escalation_chain_id

HTTP request

GET {{API_URL}}/api/v1/escalation_policies/

Delete an escalation policy

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

HTTP request

DELETE {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/

Alert groups HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

List alert groups

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "I68T24C13IFW1",
      "integration_id": "CFRPV98RPR1U8",
      "route_id": "RIYGUJXCPFHXY",
      "alerts_count": 3,
      "state": "resolved",
      "created_at": "2020-05-19T12:37:01.430444Z",
      "resolved_at": "2020-05-19T13:37:01.429805Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "resolved_by": "UCGEIXI1MR1NZ",
      "title": "Memory above 90% threshold",
      "permalinks": {
        "slack": "https://ghostbusters.slack.com/archives/C1H9RESGA/p135854651500008",
        "telegram": "https://t.me/c/5354/1234?thread=1234"
      },
      "silenced_at": "2020-05-19T13:37:01.429805Z",
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

These available filter parameters should be provided as GET arguments:

id
route_id
integration_id
state

HTTP request

GET {{API_URL}}/api/v1/alert_groups/

Alert group details

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \
  --request GET \
  --header "Authorization: meowmeowmeow"

HTTP request

GET {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>

Acknowledge an alert group

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \
  --request POST \
  --header "Authorization: meowmeowmeow"

HTTP request

POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/acknowledge

Unacknowledge an alert group

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \
  --request POST \
  --header "Authorization: meowmeowmeow"

HTTP request

POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/unacknowledge

Resolve an alert group

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \
  --request POST \
  --header "Authorization: meowmeowmeow"

HTTP request

POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/resolve

Unresolve an alert group

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \
  --request POST \
  --header "Authorization: meowmeowmeow"

HTTP request

POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/unresolve

Delete an alert group

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "mode": "wipe"
  }'

Parameter	Required	Description
`mode`	No	The default value for this parameter is `wipe`. Using `wipe` will delete the content of the alert group but keep the metadata, which is helpful if you’ve sent sensitive information to OnCall. On the other hand, passing `delete` will fully erase the alert group and its metadata, as well as delete related messages in Slack and other platforms.

NOTE: DELETE can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using GET to be sure the data is removed.

HTTP request

DELETE {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>

Integrations HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create an integration

curl "{{API_URL}}/api/v1/integrations/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "type":"grafana"
  }'

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "acknowledge_signal": null,
    "source_link": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "msteams": {
      "title": null,
      "message": null,
      "image_url": null
    }
  }
}

Integrations are sources of alerts and alert groups for Grafana OnCall. For example, to learn how to integrate Grafana OnCall with Alertmanager refer to Alertmanager.

HTTP request

POST {{API_URL}}/api/v1/integrations/

Get integration

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

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "acknowledge_signal": null,
    "source_link": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "msteams": {
      "title": null,
      "message": null,
      "image_url": null
    }
  }
}

This endpoint retrieves an integration. Integrations are sources of alerts and alert groups for Grafana OnCall.

HTTP request

GET {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

List integrations

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "CFRPV98RPR1U8",
      "name": "Grafana :blush:",
      "team_id": null,
      "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
      "inbound_email": null,
      "type": "grafana",
      "default_route": {
        "id": "RVBE4RKQSCGJ2",
        "escalation_chain_id": "F5JU6KJET33FE",
        "slack": {
          "channel_id": "CH23212D"
        }
      },
      "templates": {
        "grouping_key": null,
        "resolve_signal": null,
        "acknowledge_signal": null,
        "source_link": null,
        "slack": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "web": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "sms": {
          "title": null
        },
        "phone_call": {
          "title": null
        },
        "telegram": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "email": {
          "title": null,
          "message": null
        },
        "msteams": {
          "title": null,
          "message": null,
          "image_url": null
        }
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

HTTP request

GET {{API_URL}}/api/v1/integrations/

Update integration

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "templates": {
          "grouping_key": null,
          "resolve_signal": null,
          "slack": {
             "title": null,
             "message": null,
             "image_url": null
          }
      }
  }'

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    }
  }
}

HTTP request

PUT {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

Delete integration

Deleted integrations will stop recording new alerts from monitoring. Integration removal won’t trigger removal of related alert groups or alerts.

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow"

HTTP request

DELETE {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

OnCall shifts HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create an OnCall shift

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:

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

Parameter	Unique	Required	Description
`name`	Yes	Yes	On-call shift name.
`type`	No	Yes	One of: `single_event`, `recurrent_event`, `rolling_users`.
`team_id`	No	ID of the team.
`time_zone`	No	Optional	On-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.
`level`	No	Optional	Priority 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.
`start`	No	Yes	Start 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”).
`duration`	No	Yes	Duration of the event.
`frequency`	No	If type = `recurrent_event` or `rolling_users`	One of: `hourly`, `daily`, `weekly`, `monthly`.
`interval`	No	Optional	This 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`.
`until`	No	Optional	When 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_start`	No	Optional	Start 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_day`	No	Optional	List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`.
`by_month`	No	Optional	List of months. Valid values are `1` to `12`.
`by_monthday`	No	Optional	List of days of the month. Valid values are `1` to `31` or `-31` to `-1`.
`users`	No	Optional	List of on-call users.
`rolling_users`	No	Optional	List 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_index`	No	Optional	Index 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

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:

{
  "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

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:

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

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

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:

{
  "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

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>/

Outgoing Webhooks HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Outgoing Webhooks

⚠️ A note about actions: Before version v1.3.11 webhooks existed as actions within the API, the /actions endpoint remains available and is compatible with previous callers but under the hood it will interact with the new webhooks objects. It is recommended to use the /webhooks endpoint going forward which has more features.

For more details about specific fields of a webhook, refer to Outgoing webhooks.

List webhooks

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

The above command returns JSON structured in the following way:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "{{WEBHOOK_UID}}",
      "name": "Demo Webhook",
      "is_webhook_enabled": true,
      "team": null,
      "data": "{\"labels\" : {{ alert_payload.commonLabels | tojson()}}}",
      "username": null,
      "password": null,
      "authorization_header": "****************",
      "trigger_template": null,
      "headers": null,
      "url": "https://example.com",
      "forward_all": false,
      "http_method": "POST",
      "trigger_type": "acknowledge",
      "integration_filter": [
        "CRV8A5MXC751A"
      ]
    }
  ],
  "page_size": 50,
  "count": 1,
  "current_page_number": 1,
  "total_pages": 1
}

Get webhook

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

The above command returns JSON structured in the following way:

{
  "id": "{{WEBHOOK_UID}}",
  "name": "Demo Webhook",
  "is_webhook_enabled": true,
  "team": null,
  "data": "{\"labels\" : {{ alert_payload.commonLabels | tojson()}}}",
  "username": null,
  "password": null,
  "authorization_header": "****************",
  "trigger_template": null,
  "headers": null,
  "url": "https://example.com",
  "forward_all": false,
  "http_method": "POST",
  "trigger_type": "acknowledge",
  "integration_filter": [
    "CRV8A5MXC751A"
  ]
}

Create webhook

curl "{{API_URL}}/api/v1/webhooks/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New Webhook",
    "url": "https://example.com",
    "http_method": "POST",
    "trigger_type" : "resolve"
  }'

Trigger Types

For more detail, refer to Event types.

escalation
alert group created
acknowledge
resolve
silence
unsilence
unresolve
unacknowledge
status change

HTTP Methods

POST
GET
PUT
DELETE
OPTIONS

The above command returns JSON structured in the following way:

{
  "id": "{{WEBHOOK_UID}}",
  "name": "New Webhook",
  "is_webhook_enabled": true,
  "team": null,
  "data": null,
  "username": null,
  "password": null,
  "authorization_header": null,
  "trigger_template": null,
  "headers": null,
  "url": "https://example.com",
  "forward_all": true,
  "http_method": "POST",
  "trigger_type": "resolve",
  "integration_filter": null
}

Update webhook

curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "is_webhook_enabled": false
  }'

The above command returns JSON structured in the following way:

{
  "id": "{{WEBHOOK_UID}}",
  "name": "New Webhook",
  "is_webhook_enabled": false,
  "team": null,
  "data": null,
  "username": null,
  "password": null,
  "authorization_header": null,
  "trigger_template": null,
  "headers": null,
  "url": "https://example.com",
  "forward_all": true,
  "http_method": "POST",
  "trigger_type": "resolve",
  "integration_filter": null
}

Delete webhook

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

Get webhook responses

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

The above command returns JSON structured in the following way:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "timestamp": "2023-08-18T16:38:23.106015Z",
      "url": "https://example.com",
      "request_trigger": "",
      "request_headers": "{\"Authorization\": \"****************\"}",
      "request_data": "{\"labels\": {\"alertname\": \"InstanceDown\", \"job\": \"node\", \"severity\": \"critical\"}}",
      "status_code": 200,
      "content": "",
      "event_data": "{\"event\": {\"type\": \"acknowledge\", \"time\": \"2023-08-18T16:38:21.442981+00:00\"}, \"user\": {\"id\": \"UK49JJNPZMFLJ\", \"username\": \"oncall\", \"email\": \"admin@localhost\"}, \"alert_group\": {\"id\": \"IZQERPWKWCGH1\", \"integration_id\": \"CRV8A5MXC751A\", \"route_id\": \"RWNCT6C77M3WM\", \"alerts_count\": 1, \"state\": \"acknowledged\", \"created_at\": \"2023-08-18T16:34:27.678406Z\", \"resolved_at\": null, \"acknowledged_at\": \"2023-08-18T16:38:21.442981Z\", \"title\": \"[firing:2] InstanceDown \", \"permalinks\": {\"slack\": null, \"telegram\": null, \"web\": \"http://localhost:3000/a/grafana-oncall-app/alert-groups/IZQERPWKWCGH1\"}}, \"alert_group_id\": \"IZQERPWKWCGH1\", \"alert_payload\": {\"alerts\": [{\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"production\", \"instance\": \"localhost:8081\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8081 down\", \"description\": \"localhost:8081 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f404ecabc8dd5cd7\", \"generatorURL\": \"\"}, {\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"canary\", \"instance\": \"localhost:8082\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8082 down\", \"description\": \"localhost:8082 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f8f08d4e32c61a9d\", \"generatorURL\": \"\"}], \"status\": \"firing\", \"version\": \"4\", \"groupKey\": \"{}:{alertname=\\\"InstanceDown\\\"}\", \"receiver\": \"combo\", \"numFiring\": 2, \"externalURL\": \"\", \"groupLabels\": {\"alertname\": \"InstanceDown\"}, \"numResolved\": 0, \"commonLabels\": {\"job\": \"node\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"truncatedAlerts\": 0, \"commonAnnotations\": {}}, \"integration\": {\"id\": \"CRV8A5MXC751A\", \"type\": \"alertmanager\", \"name\": \"One - Alertmanager\", \"team\": null}, \"notified_users\": [], \"users_to_be_notified\": []}"
    },
    {
      "timestamp": "2023-08-18T16:34:38.580574Z",
      "url": "https://example.com",
      "request_trigger": "",
      "request_headers": null,
      "request_data": "Data - Template Warning: Object of type Undefined is not JSON serializable",
      "status_code": null,
      "content": null,
      "event_data": "{\"event\": {\"type\": \"acknowledge\", \"time\": \"2023-08-18T16:34:37.940655+00:00\"}, \"user\": {\"id\": \"UK49JJNPZMFLJ\", \"username\": \"oncall\", \"email\": \"admin@localhost\"}, \"alert_group\": {\"id\": \"IZQERPWKWCGH1\", \"integration_id\": \"CRV8A5MXC751A\", \"route_id\": \"RWNCT6C77M3WM\", \"alerts_count\": 1, \"state\": \"acknowledged\", \"created_at\": \"2023-08-18T16:34:27.678406Z\", \"resolved_at\": null, \"acknowledged_at\": \"2023-08-18T16:34:37.940655Z\", \"title\": \"[firing:2] InstanceDown \", \"permalinks\": {\"slack\": null, \"telegram\": null, \"web\": \"http://localhost:3000/a/grafana-oncall-app/alert-groups/IZQERPWKWCGH1\"}}, \"alert_group_id\": \"IZQERPWKWCGH1\", \"alert_payload\": {\"alerts\": [{\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"production\", \"instance\": \"localhost:8081\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8081 down\", \"description\": \"localhost:8081 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f404ecabc8dd5cd7\", \"generatorURL\": \"\"}, {\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"canary\", \"instance\": \"localhost:8082\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8082 down\", \"description\": \"localhost:8082 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f8f08d4e32c61a9d\", \"generatorURL\": \"\"}], \"status\": \"firing\", \"version\": \"4\", \"groupKey\": \"{}:{alertname=\\\"InstanceDown\\\"}\", \"receiver\": \"combo\", \"numFiring\": 2, \"externalURL\": \"\", \"groupLabels\": {\"alertname\": \"InstanceDown\"}, \"numResolved\": 0, \"commonLabels\": {\"job\": \"node\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"truncatedAlerts\": 0, \"commonAnnotations\": {}}, \"integration\": {\"id\": \"CRV8A5MXC751A\", \"type\": \"alertmanager\", \"name\": \"One - Alertmanager\", \"team\": null}, \"notified_users\": [], \"users_to_be_notified\": []}"
    }
  ],
  "page_size": 50,
  "count": 2,
  "current_page_number": 1,
  "total_pages": 1
}

Personal Notification Rules HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Post a personal notification rule

curl "{{API_URL}}/api/v1/personal_notification_rules/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "user_id": "U4DNY931HHJS5",
      "type": "notify_by_sms"
  }'

The above command returns JSON structured in the following way:

{
  "id": "NT79GA9I7E4DJ",
  "user_id": "U4DNY931HHJS5",
  "position": 0,
  "important": false,
  "type": "notify_by_sms"
}

Parameter	Required	Description
`user_id`	Yes	User ID
`position`	Optional	Personal notification rules execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down on the list.
`type`	Yes	One of: `wait`, `notify_by_slack`, `notify_by_sms`, `notify_by_phone_call`, `notify_by_telegram`, `notify_by_email`.
`duration`	Optional	A time in secs when type `wait` is chosen for `type`.
`important`	Optional	Boolean value indicates if a rule is “important”. Default is `false`.

HTTP request

POST {{API_URL}}/api/v1/personal_notification_rules/

Get personal notification rule

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

The above command returns JSON structured in the following way:

{
  "id": "ND9EHN5LN1DUU",
  "user_id": "U4DNY931HHJS5",
  "position": 1,
  "duration": 300,
  "important": false,
  "type": "wait"
}

HTTP request

GET {{API_URL}}/api/v1/personal_notification_rules/<PERSONAL_NOTIFICATION_RULE_ID>/

List personal notification rules

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

The above command returns JSON structured in the following ways:

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "NT79GA9I7E4DJ",
      "user_id": "U4DNY931HHJS5",
      "position": 0,
      "important": false,
      "type": "notify_by_sms"
    },
    {
      "id": "ND9EHN5LN1DUU",
      "user_id": "U4DNY931HHJS5",
      "position": 1,
      "duration": 300,
      "important": false,
      "type": "wait"
    },
    {
      "id": "NEF49YQ1HNPDD",
      "user_id": "U4DNY931HHJS5",
      "position": 2,
      "important": false,
      "type": "notify_by_phone_call"
    },
    {
      "id": "NWAL6WFJNWDD8",
      "user_id": "U4DNY931HHJS5",
      "position": 0,
      "important": true,
      "type": "notify_by_phone_call"
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

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

user_id
important

HTTP Request

GET {{API_URL}}/api/v1/personal_notification_rules/

Delete a personal notification rule

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

HTTP request

DELETE {{API_URL}}/api/v1/personal_notification_rules/<PERSONAL_NOTIFICATION_RULE_ID>/

Resolution Notes HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create a resolution note

curl "{{API_URL}}/api/v1/resolution_notes/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "alert_group_id": "I68T24C13IFW1",
      "text": "Demo resolution note"
  }'

The above command returns JSON structured in the following way:

{
  "id": "M4BTQUS3PRHYQ",
  "alert_group_id": "I68T24C13IFW1",
  "author": "U4DNY931HHJS5",
  "source": "web",
  "created_at": "2020-06-19T12:40:01.429805Z",
  "text": "Demo resolution note"
}

Parameter	Required	Description
`alert_group_id`	Yes	Alert group ID
`text`	Yes	Resolution note text

HTTP request

POST {{API_URL}}/api/v1/resolution_notes/

Get a resolution note

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

The above command returns JSON structured in the following way:

{
  "id": "M4BTQUS3PRHYQ",
  "alert_group_id": "I68T24C13IFW1",
  "author": "U4DNY931HHJS5",
  "source": "web",
  "created_at": "2020-06-19T12:40:01.429805Z",
  "text": "Demo resolution note"
}

HTTP request

GET {{API_URL}}/api/v1/resolution_notes/<RESOLUTION_NOTE_ID>/

List resolution notes

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "M4BTQUS3PRHYQ",
      "alert_group_id": "I68T24C13IFW1",
      "author": "U4DNY931HHJS5",
      "source": "web",
      "created_at": "2020-06-19T12:40:01.429805Z",
      "text": "Demo resolution note"
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

The following available filter parameter should be provided as a GET argument:

alert_group_id

HTTP request

GET {{API_URL}}/api/v1/resolution_notes/

Update a resolution note

curl "{{API_URL}}/api/v1/resolution_notes/M4BTQUS3PRHYQ/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "text": "Demo resolution note updated"
  }'

The above command returns JSON structured in the following way:

{
  "id": "M4BTQUS3PRHYQ",
  "alert_group_id": "I68T24C13IFW1",
  "author": "U4DNY931HHJS5",
  "source": "web",
  "created_at": "2020-06-19T12:40:01.429805Z",
  "text": "Demo resolution note updated"
}

HTTP request

PUT {{API_URL}}/api/v1/resolution_notes/<RESOLUTION_NOTE_ID>/

Delete a resolution note

curl "{{API_URL}}/api/v1/resolution_notes/M4BTQUS3PRHYQ/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow"

HTTP request

DELETE {{API_URL}}/api/v1/resolution_notes/<RESOLUTION_NOTE_ID>/

Routes HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create a route

curl "{{API_URL}}/api/v1/routes/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "integration_id": "CFRPV98RPR1U8",
      "escalation_chain_id": "F5JU6KJET33FE",
      "routing_regex": "us-(east|west)",
      "position": 0,
      "slack": {
        "channel_id": "CH23212D"
      }
  }'

The above command returns JSON structured in the following way:

{
  "id": "RIYGUJXCPFHXY",
  "integration_id": "CFRPV98RPR1U8",
  "escalation_chain_id": "F5JU6KJET33FE",
  "routing_regex": "us-(east|west)",
  "position": 0,
  "is_the_last_route": false,
  "slack": {
    "channel_id": "CH23212D"
  }
}

Routes allow you to direct different alerts to different messenger channels and escalation chains. Useful for:

Important/non-important alerts
Alerts for different engineering groups
Snoozing spam & debugging alerts

Parameter	Unique	Required	Description
`integration_id`	No	Yes	Each route is assigned to a specific integration.
`escalation_chain_id`	No	Yes	Each route is assigned a specific escalation chain. Explicitly pass `null` to create a route without an escalation chain assigned.
`routing_type`	Yes	No	Routing type that can be either `jinja2` or `regex`(default value)
`routing_regex`	Yes	Yes	Jinja2 template or Python Regex query (use https://regex101.com/ for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload.
`position`	Yes	Optional	Route matching is performed one after another starting from position=`0`. Position=`-1` will put the route to the end of the list before `is_the_last_route`. A new route created with a position of an existing route will move the old route (and all following routes) down in the list.
`slack`	Yes	Optional	Dictionary with Slack-specific settings for a route.

HTTP request

POST {{API_URL}}/api/v1/routes/

Get a route

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

The above command returns JSON structured in the following way:

{
  "id": "RIYGUJXCPFHXY",
  "integration_id": "CFRPV98RPR1U8",
  "escalation_chain_id": "F5JU6KJET33FE",
  "routing_regex": "us-(east|west)",
  "position": 0,
  "is_the_last_route": false,
  "slack": {
    "channel_id": "CH23212D"
  }
}

HTTP request

GET {{API_URL}}/api/v1/routes/<ROUTE_ID>/

List routes

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

The above command returns JSON structured in the following way:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "RIYGUJXCPFHXY",
      "integration_id": "CFRPV98RPR1U8",
      "escalation_chain_id": "F5JU6KJET33FE",
      "routing_regex": "us-(east|west)",
      "position": 0,
      "is_the_last_route": false,
      "slack": {
        "channel_id": "CH23212D"
      }
    },
    {
      "id": "RVBE4RKQSCGJ2",
      "integration_id": "CFRPV98RPR1U8",
      "escalation_chain_id": "F5JU6KJET33FE",
      "routing_regex": ".*",
      "position": 1,
      "is_the_last_route": true,
      "slack": {
        "channel_id": "CH23212D"
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 25,
  "total_pages": 1
}

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

integration_id
routing_regex (Exact match)

HTTP request

GET {{API_URL}}/api/v1/routes/

Update route

curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "routing_regex": "us-(east|west)",
      "position": 0,
      "slack": {
        "channel_id": "CH23212D"
      }
  }'

The above command returns JSON structured in the following way:

{
  "id": "RIYGUJXCPFHXY",
  "integration_id": "CFRPV98RPR1U8",
  "escalation_chain_id": "F5JU6KJET33FE",
  "routing_regex": "us-(east|west)",
  "position": 0,
  "is_the_last_route": false,
  "slack": {
    "channel_id": "CH23212D"
  }
}

HTTP request

PUT {{API_URL}}/api/v1/routes/<ROUTE_ID>/

Delete a route

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

HTTP request

DELETE {{API_URL}}/api/v1/routes/<ROUTE_ID>/

Schedule HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create a schedule

curl "{{API_URL}}/api/v1/schedules/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "Demo schedule iCal",
      "ical_url_primary": "https://example.com/meow_calendar.ics",
      "slack": {
          "channel_id": "MEOW_SLACK_ID",
          "user_group_id": "MEOW_SLACK_ID"
      }
  }'

The above command returns JSON structured in the following way:

{
  "id": "SBM7DV7BKFUYU",
  "name": "Demo schedule iCal",
  "type": "ical",
  "team_id": null,
  "ical_url_primary": "https://example.com/meow_calendar.ics",
  "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
  "on_call_now": ["U4DNY931HHJS5"],
  "slack": {
    "channel_id": "MEOW_SLACK_ID",
    "user_group_id": "MEOW_SLACK_ID"
  }
}

Parameter	Unique	Required	Description
`name`	Yes	Yes	Schedule name.
`type`	No	Yes	Schedule type. May be `ical` (used for iCalendar integration), `calendar` (used for manually created on-call shifts) or `web` (for web UI managed schedules).
`team_id`	No	No	ID of the team.
`time_zone`	No	Yes	Schedule time zone. It is used for manually added on-call shifts in Schedules with type `calendar`. Default time zone is `UTC`. For more information about time zones, see time zones. Not used for schedules with type `ical`.
`ical_url_primary`	No	If type = `ical`	URL of external iCal calendar for schedule with type `ical`.
`ical_url_overrides`	No	Optional	URL of external iCal calendar for schedule with any type. Events from this calendar override events from primary calendar or from on-call shifts.
`enable_web_overrides`	No	Optional	Whether to enable web overrides or not. Setting specific for API/Terraform based schedules (`calendar` type).
`slack`	No	Optional	Dictionary with Slack-specific settings for a schedule. Includes `channel_id` and `user_group_id` fields, that take a channel ID and a user group ID from Slack.
`shifts`	No	Optional	List of shifts. Used for manually added on-call shifts in Schedules with type `calendar`.

HTTP request

POST {{API_URL}}/api/v1/schedules/

Get a schedule

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

The above command returns JSON structured in the following way:

{
  "id": "SBM7DV7BKFUYU",
  "name": "Demo schedule iCal",
  "type": "ical",
  "team_id": null,
  "ical_url_primary": "https://example.com/meow_calendar.ics",
  "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
  "on_call_now": ["U4DNY931HHJS5"],
  "slack": {
    "channel_id": "MEOW_SLACK_ID",
    "user_group_id": "MEOW_SLACK_ID"
  }
}

HTTP request

GET {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

List schedules

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

The above command returns JSON structured in the following way:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "SBM7DV7BKFUYU",
      "name": "Demo schedule iCal",
      "type": "ical",
      "team_id": null,
      "ical_url_primary": "https://example.com/meow_calendar.ics",
      "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
      "on_call_now": ["U4DNY931HHJS5"],
      "slack": {
        "channel_id": "MEOW_SLACK_ID",
        "user_group_id": "MEOW_SLACK_ID"
      }
    },
    {
      "id": "S3Z477AHDXTMF",
      "name": "Demo schedule Calendar",
      "type": "calendar",
      "team_id": null,
      "time_zone": "America/New_York",
      "on_call_now": ["U4DNY931HHJS5"],
      "shifts": ["OH3V5FYQEYJ6M", "O9WTH7CKM3KZW"],
      "ical_url_overrides": null,
      "slack": {
        "channel_id": "MEOW_SLACK_ID",
        "user_group_id": "MEOW_SLACK_ID"
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

The following available filter parameter should be provided as a GET argument:

name (Exact match)

HTTP request

GET {{API_URL}}/api/v1/schedules/

Update a schedule

curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Demo schedule iCal",
    "ical_url": "https://example.com/meow_calendar.ics",
    "slack": {
        "channel_id": "MEOW_SLACK_ID"
    }
  }'

The above command returns JSON structured in the following way:

{
  "id": "SBM7DV7BKFUYU",
  "name": "Demo schedule iCal",
  "type": "ical",
  "team_id": null,
  "ical_url_primary": "https://example.com/meow_calendar.ics",
  "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
  "on_call_now": ["U4DNY931HHJS5"],
  "slack": {
    "channel_id": "MEOW_SLACK_ID",
    "user_group_id": "MEOW_SLACK_ID"
  }
}

HTTP request

PUT {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

Delete a schedule

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

HTTP request

DELETE {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

Export a schedule’s final shifts

HTTP request

curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/final_shifts?start_date=2023-01-01&end_date=2023-02-01" \
  --request GET \
  --header "Authorization: meowmeowmeow"

The above command returns JSON structured in the following way:

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-02T09:00:00Z",
      "shift_end": "2023-01-02T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-04T09:00:00Z",
      "shift_end": "2023-01-04T17:00:00Z"
    },
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-06T09:00:00Z",
      "shift_end": "2023-01-06T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-09T09:00:00Z",
      "shift_end": "2023-01-09T17:00:00Z"
    },
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-11T09:00:00Z",
      "shift_end": "2023-01-11T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-13T09:00:00Z",
      "shift_end": "2023-01-13T17:00:00Z"
    },
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-16T09:00:00Z",
      "shift_end": "2023-01-16T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-18T09:00:00Z",
      "shift_end": "2023-01-18T17:00:00Z"
    },
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-20T09:00:00Z",
      "shift_end": "2023-01-20T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-23T09:00:00Z",
      "shift_end": "2023-01-23T17:00:00Z"
    },
    {
      "user_pk": "UC2CHRT5SD34X",
      "user_email": "alice@example.com",
      "user_username": "alice",
      "shift_start": "2023-01-25T09:00:00Z",
      "shift_end": "2023-01-25T17:00:00Z"
    },
    {
      "user_pk": "U7S8H84ARFTGN",
      "user_email": "bob@example.com",
      "user_username": "bob",
      "shift_start": "2023-01-27T09:00:00Z",
      "shift_end": "2023-01-27T17:00:00Z"
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

Caveats

Some notes on the start_date and end_date query parameters:

they are both required and should represent ISO 8601 formatted dates
end_date must be greater than or equal to start_date
end_date cannot be more than 365 days in the future from start_date

Note: you can update schedules affecting past events, which will then change the output you get from this endpoint. To get consistent information about past shifts you must be sure to avoid updating rotations in-place but apply the changes as new rotations with the right starting dates.

Example script to transform data to .csv for all of your schedules

The following Python script will generate a .csv file, oncall-report-2023-01-01-to-2023-01-31.csv. This file will contain three columns, user_pk, user_email, and hours_on_call, which represents how many hours each user was on call during the period starting January 1, 2023 to January 31, 2023 (inclusive).

import csv
import requests
from datetime import datetime

# CUSTOMIZE THE FOLLOWING VARIABLES
START_DATE = "2023-01-01"
END_DATE = "2023-01-31"
OUTPUT_FILE_NAME = f"oncall-report-{START_DATE}-to-{END_DATE}.csv"
MY_ONCALL_API_BASE_URL = "https://oncall-prod-us-central-0.grafana.net/oncall/api/v1/schedules"
MY_ONCALL_API_KEY = "meowmeowwoofwoof"

headers = {"Authorization": MY_ONCALL_API_KEY}
schedule_ids = [schedule["id"] for schedule in requests.get(MY_ONCALL_API_BASE_URL, headers=headers).json()["results"]]
user_on_call_hours = {}

for schedule_id in schedule_ids:
  response = requests.get(
    f"{MY_ONCALL_API_BASE_URL}/{schedule_id}/final_shifts?start_date={START_DATE}&end_date={END_DATE}",
    headers=headers)

  for final_shift in response.json()["results"]:
    user_pk = final_shift["user_pk"]
    end = datetime.fromisoformat(final_shift["shift_end"])
    start = datetime.fromisoformat(final_shift["shift_start"])
    shift_time_in_seconds = (end - start).total_seconds()
    shift_time_in_hours = shift_time_in_seconds / (60 * 60)

    if user_pk in user_on_call_hours:
      user_on_call_hours[user_pk]["hours_on_call"] += shift_time_in_hours
    else:
      user_on_call_hours[user_pk] = {
        "email": final_shift["user_email"],
        "hours_on_call": shift_time_in_hours,
      }

with open(OUTPUT_FILE_NAME, "w") as fp:
  csv_writer = csv.DictWriter(fp, ["user_pk", "user_email", "hours_on_call"])
  csv_writer.writeheader()

  for user_pk, user_info in user_on_call_hours.items():
    csv_writer.writerow({
      "user_pk": user_pk, "user_email": user_info["email"], "hours_on_call": user_info["hours_on_call"]})

Shift swaps HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Create a shift swap request

curl "{{API_URL}}/api/v1/shift_swaps/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
        "schedule": "SRJWJCMKD68AL",
        "swap_start": "2026-06-11T00:00:00Z",
        "swap_end": "2026-07-19T22:00:00Z",
        "description": "Anyone to cover my shifts?",
        "beneficiary": "UWJWIN8MQ1GYL"
  }'

The above command returns JSON structured in the following way:

{
   "benefactor" : null,
   "beneficiary" : "UWJWIN8MQ1GYL",
   "created_at" : "2023-08-11T19:20:17.064677Z",
   "description" : "Anyone to cover my shifts?",
   "id" : "SSRG1TDNBMJQ1NC",
   "schedule" : "SRJWJCMKD68AL",
   "shifts" : [
      {
         "all_day" : false,
         "calendar_type" : 0,
         "end" : "2026-06-11T03:00:00Z",
         "is_empty" : false,
         "is_gap" : false,
         "is_override" : false,
         "missing_users" : [],
         "priority_level" : 2,
         "shift" : {
            "pk" : "OTI13GNNE5V1L"
         },
         "source" : "web",
         "start" : "2026-06-11T00:00:00Z",
         "users" : [
            {
               "avatar_full" : "http://avatar.url",
               "display_name" : "testing",
               "email" : "testing",
               "pk" : "UWJWIN8MQ1GYL",
               "swap_request" : {
                  "pk" : "SSRG1TDNBMJQ1NC"
               }
            }
         ]
      }
   ],
   "status" : "open",
   "swap_end" : "2026-07-19T22:00:00.000000Z",
   "swap_start" : "2026-06-11T00:00:00.000000Z",
   "updated_at" : "2023-08-11T19:20:17.064922Z"
}

Parameter	Unique	Required	Description
`schedule`	No	Yes	ID of the schedule.
`swap_start`	No	Yes	Start date/time for the swap request. Must be a ISO 8601 formatted datetime string.
`swap_end`	No	No	End date/time for the swap request. Must be a ISO 8601 formatted datetime string.
`description`	No	Optional	A description message to be displayed along the request.
`beneficiary`	No	Yes	ID of the user requesting the swap.

HTTP request

POST {{API_URL}}/api/v1/shift_swaps/

Get a shift swap request

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

The above command returns JSON structured in the following way:

{
   "benefactor" : null,
   "beneficiary" : "UWJWIN8MQ1GYL",
   "created_at" : "2023-08-11T19:20:17.064677Z",
   "description" : "Anyone to cover my shifts?",
   "id" : "SSRG1TDNBMJQ1NC",
   "schedule" : "SRJWJCMKD68AL",
   "shifts" : [
      {
         "all_day" : false,
         "calendar_type" : 0,
         "end" : "2026-06-11T03:00:00Z",
         "is_empty" : false,
         "is_gap" : false,
         "is_override" : false,
         "missing_users" : [],
         "priority_level" : 2,
         "shift" : {
            "pk" : "OTI13GNNE5V1L"
         },
         "source" : "web",
         "start" : "2026-06-11T00:00:00Z",
         "users" : [
            {
               "avatar_full" : "http://avatar.url",
               "display_name" : "testing",
               "email" : "testing",
               "pk" : "UWJWIN8MQ1GYL",
               "swap_request" : {
                  "pk" : "SSRG1TDNBMJQ1NC"
               }
            }
         ]
      }
   ],
   "status" : "open",
   "swap_end" : "2026-07-19T22:00:00.000000Z",
   "swap_start" : "2026-06-11T00:00:00.000000Z",
   "updated_at" : "2023-08-11T19:20:17.064922Z"
}

HTTP request

GET {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/

List shift swap requests

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

The above command returns JSON structured in the following way:

{
   "count" : 2,
   "current_page_number" : 1,
   "next" : null,
   "page_size" : 50,
   "previous" : null,
   "results" : [
      {
         "benefactor" : "UWJWIN8MQ1GYL",
         "beneficiary" : "UCGEIXI1MR1NZ",
         "created_at" : "2023-08-07T18:44:15.249679Z",
         "description" : "Taking a few days off.",
         "id" : "SSRK2EH2TR6E4F9",
         "schedule" : "SRZZFY1QI9FLL",
         "status" : "taken",
         "swap_end" : "2024-09-29T03:00:18.000000Z",
         "swap_start" : "2024-09-26T03:00:18.000000Z",
         "updated_at" : "2024-08-07T18:44:15.249960Z"
      },
      {
         "benefactor" : null,
         "beneficiary" : "UWJWIN8MQ1GYL",
         "created_at" : "2023-08-11T19:20:17.064677Z",
         "description" : "Anyone to cover my shifts?",
         "id" : "SSRG1TDNBMJQ1NC",
         "schedule" : "SRJWJCMKD68AL",
         "status" : "open",
         "swap_end" : "2026-07-19T22:00:00.000000Z",
         "swap_start" : "2026-06-11T00:00:00.000000Z",
         "updated_at" : "2023-08-11T19:20:17.064922Z"
      }
   ],
   "total_pages" : 1
}

The following available filter parameters may be provided as a GET arguments:

starting_after (an ISO 8601 timestamp string, filter requests starting after the specified datetime)
schedule_id (Exact match, schedule ID)
beneficiary (Exact match, user ID)
benefactor (Exact match, user ID)
open_only (set to true to filter active untaken requests only)

HTTP request

GET {{API_URL}}/api/v1/shift_swaps/

Update a shift swap request

curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
        "schedule": "SRJWJCMKD68AL",
        "swap_start": "2026-06-11T00:00:00Z",
        "swap_end": "2026-07-20T22:00:00Z"
  }'

The above command returns JSON structured in the following way:

{
   "benefactor" : null,
   "beneficiary" : "UWJWIN8MQ1GYL",
   "created_at" : "2023-08-11T19:20:17.064677Z",
   "description" : "Anyone to cover my shifts?",
   "id" : "SSRG1TDNBMJQ1NC",
   "schedule" : "SRJWJCMKD68AL",
   "shifts" : [
      {
         "all_day" : false,
         "calendar_type" : 0,
         "end" : "2026-06-11T03:00:00Z",
         "is_empty" : false,
         "is_gap" : false,
         "is_override" : false,
         "missing_users" : [],
         "priority_level" : 2,
         "shift" : {
            "pk" : "OTI13GNNE5V1L"
         },
         "source" : "web",
         "start" : "2026-06-11T00:00:00Z",
         "users" : [
            {
               "avatar_full" : "http://avatar.url",
               "display_name" : "testing",
               "email" : "testing",
               "pk" : "UWJWIN8MQ1GYL",
               "swap_request" : {
                  "pk" : "SSRG1TDNBMJQ1NC"
               }
            }
         ]
      }
   ],
   "status" : "open",
   "swap_end" : "2026-07-20T22:00:00.000000Z",
   "swap_start" : "2026-06-11T00:00:00.000000Z",
   "updated_at" : "2023-08-11T19:45:53.096811Z"
}

HTTP request

PUT {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/

Delete a shift swap request

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

HTTP request

DELETE {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/

Take a shift swap request

curl "{{API_URL}}/api/v1/shift_swaps/SSRG1TDNBMJQ1NC/take" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
        "benefactor": "UCGEIXI1MR1NZ"
  }'

The above command returns JSON structured in the following way:

{
   "benefactor" : "UCGEIXI1MR1NZ",
   "beneficiary" : "UWJWIN8MQ1GYL",
   "created_at" : "2023-08-11T19:20:17.064677Z",
   "description" : "Anyone to cover my shifts?",
   "id" : "SSRG1TDNBMJQ1NC",
   "schedule" : "SRJWJCMKD68AL",
   "shifts" : [
      {
         "all_day" : false,
         "calendar_type" : 0,
         "end" : "2026-06-11T03:00:00Z",
         "is_empty" : false,
         "is_gap" : false,
         "is_override" : false,
         "missing_users" : [],
         "priority_level" : 2,
         "shift" : {
            "pk" : "OTI13GNNE5V1L"
         },
         "source" : "web",
         "start" : "2026-06-11T00:00:00Z",
         "users" : [
            {
               "avatar_full" : "http://avatar.url",
               "display_name" : "anotherone",
               "email" : "anotherone",
               "pk" : "UCGEIXI1MR1NZ",
               "swap_request" : {
                  "pk" : "SSRG1TDNBMJQ1NC",
                  "user" : {
                     "avatar_full" : "http://avatar.url",
                     "display_name" : "testing",
                     "email" : "testing",
                     "pk" : "UWJWIN8MQ1GYL"
                  }
               }
            }
         ]
      }
   ],
   "status" : "taken",
   "swap_end" : "2026-07-20T22:00:00.000000Z",
   "swap_start" : "2026-06-11T00:00:00.000000Z",
   "updated_at" : "2023-08-11T19:51:38.622037Z"
}

Parameter	Unique	Required	Description
`benefactor`	No	Yes	ID of the user taking the swap.

HTTP request

POST {{API_URL}}/api/v1/shift_swaps/<SHIFT_SWAP_REQUEST_ID>/take

Slack Channels HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

List Slack Channels

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "meow_channel",
      "slack_id": "MEOW_SLACK_ID"
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

The following available filter parameter should be provided as a GET argument:

channel_name

HTTP Request

GET {{API_URL}}/api/v1/slack_channels/

OnCall User Groups HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

List user groups

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "GPFAPH7J7BKJB",
      "type": "slack_based",
      "slack": {
        "id": "MEOW_SLACK_ID",
        "name": "Meow Group",
        "handle": "meow_group"
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

Parameter	Unique	Description
`id`	Yes	User Group ID
`type`	No	Slack-defined user groups
`slack`	No	Metadata retrieved from Slack.

HTTP request

GET {{API_URL}}/api/v1/user_groups/

Grafana OnCall Users HTTP API

Tue, 07 Apr 2026 10:28:26 +0000

Get a user

This endpoint retrieves the user object.

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

The above command returns JSON structured in the following way:

{
  "id": "U4DNY931HHJS5",
  "email": "public-api-demo-user-1@grafana.com",
  "slack": [
    {
      "user_id": "UALEXSLACKDJPK",
      "team_id": "TALEXSLACKDJPK"
    }
  ],
  "username": "alex",
  "role": "admin",
  "timezone": "UTC",
  "teams": []
}

HTTP request

GET {{API_URL}}/api/v1/users/<USER_ID>/

Use {{API_URL}}/api/v1/users/current to retrieve the current user.

Parameter	Unique	Description
`id`	Yes/org	User ID
`email`	Yes/org	User e-mail
`slack`	Yes/org	List of user IDs from connected Slack. User linking key is e-mail.
`username`	Yes/org	User username
`role`	No	One of: `user`, `observer`, `admin`.
`timezone`	No	timezone of the user one of time zones.
`teams`	No	List of team IDs the user belongs to

List Users

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

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "U4DNY931HHJS5",
      "email": "public-api-demo-user-1@grafana.com",
      "slack": [
        {
          "user_id": "UALEXSLACKDJPK",
          "team_id": "TALEXSLACKDJPK"
        }
      ],
      "username": "alex",
      "role": "admin",
      "timezone": "UTC",
      "teams": ["TAAM1K1NNEHAG"]
    }
  ],
  "current_page_number": 1,
  "page_size": 100,
  "total_pages": 1
}

This endpoint retrieves all users.

The following available filter parameter should be provided as a GET argument:

username (Exact match)

HTTP request

GET {{API_URL}}/api/v1/users/