---
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. However, some endpoints require user-specific context and must be accessed using 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](/docs/grafana-cloud/alerting-and-irm/irm/set-up/admin-settings).

> Note
> 
> Certain OnCall API endpoints require user context and cannot be accessed with service account tokens. For these endpoints, use a [legacy OnCall API key](#authenticate-using-a-legacy-oncall-api-key). These exceptions are noted in the relevant endpoint documentation.

### 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](/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](/docs/grafana/latest/administration/service-accounts/#service-account-tokens) for more information.

### Authenticate using a legacy OnCall API key

Legacy OnCall API keys are user-specific and may be required for endpoints that record user actions.

shell ![Copy code to clipboard](/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](/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"
```

## 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](/docs/grafana-cloud/alerting-and-irm/irm/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`.