Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Observe and actbreadcrumb arrow Manage on-call and incidentsbreadcrumb arrow Referencebreadcrumb arrow OnCall API
Grafana Cloud

OnCall API Reference

Use the following guidelines for the OnCall API in Grafana IRM.

Authentication

You can authenticate with the OnCall API in Grafana IRM using one of two methods:

  1. Grafana Cloud service account tokens (recommended)
  2. OnCall API keys (legacy)

Grafana Cloud service account tokens are the preferred method for most use cases. They allow you to assign granular permissions, rotate tokens, and manage access centrally. A service account token can acknowledge, resolve, and silence alert groups when it has the grafana-irm-app.alert-groups:write permission. A few endpoints still accept only a legacy OnCall API key.

To locate your OnCall API endpoint, navigate to IRM > Settings > Admin & API in Grafana Cloud. For more details, see the IRM settings documentation.

Note

GET /api/v1/info, POST /api/v1/make_call, and POST /api/v1/send_sms accept only a legacy OnCall API key. Service account tokens can’t call GET /api/v1/users/current/, because a service account has no user profile. For the full list, refer to Service account token limitations.

Service account tokens provide secure, flexible access management. To authenticate:

  • Add the Authorization header with your service account token, using the Bearer prefix.
  • Add the X-Grafana-URL header specifying your Grafana Cloud stack.
shell 
curl "https://your-oncall-endpoint/api/..." \
  --header "Authorization: Bearer <service account token>" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

Refer to the Service account tokens documentation for more information.

Authenticate using a legacy OnCall API key

Legacy OnCall API keys are tied to the user who created them. Use one when an endpoint doesn’t accept a service account token.

shell 
curl "https://your-oncall-endpoint/api/..." \
  --header "Authorization: <oncall-api-key>"

Note

OnCall API tokens are only visible to the user who created them. Other users cannot view or manage tokens they did not create.

Pagination

List endpoints such as List Integrations or List Alert Groups return multiple objects.

The OnCall API returns them in pages. Note that the page size may vary.

ParameterMeaning
countThe total number of items. It can be 0 if a request does not return any data.
nextA link to the next page. It can be null if the next page does not contain any data.
previousA link to the previous page. It can be null if the previous page does not contain any data.
resultsThe data list. Can be [] if a request does not return any data.

To control the size of the page and which page to access use the page and perpage query parameters. For example:

shell 
curl "{{API_URL}}/api/v1/alert_groups/?page=5&perpage=10" \
  --request GET \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

perpage is capped at 100. Values above 100 are served at the maximum page size instead of returning an error.

Rate limits

For full details on all IRM rate limits — including alert ingestion limits, API limits, Slack limits, and how to request increases — refer to the Rate limits reference.

API rate limits

ScopeAmountTime window
API requests per API key3001 minute

Requests that exceed this limit receive HTTP 429 Too Many Requests.