---
title: "OnCall API reference | Grafana Cloud documentation"
description: "Reference material for Grafana OnCall API."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/set-up/admin-settings).

> Note
> 
> `GET /api/v1/info`, `POST /api/v1/make_call`, and `POST /api/v1/send_sms` accept only a [legacy OnCall API key](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/#authenticate-using-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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/set-up/infra-as-code/#service-account-token-limitations).

### Authenticate using a service account token (recommended)

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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens) 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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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.

Expand table

| Parameter  | Meaning                                                                                       |
|------------|-----------------------------------------------------------------------------------------------|
| `count`    | The total number of items. It can be `0` if a request does not return any data.               |
| `next`     | A link to the next page. It can be `null` if the next page does not contain any data.         |
| `previous` | A link to the previous page. It can be `null` if the previous page does not contain any data. |
| `results`  | The 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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/rate-limits).

### API rate limits

Expand table

| Scope                    | Amount | Time window |
|--------------------------|--------|-------------|
| API requests per API key | 300    | 1 minute    |

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