--- title: "Grafana OnCall teams HTTP API | Grafana Cloud documentation" description: "Grafana OnCall teams HTTP API Get a team Required permission: grafana-irm-app.user-settings:read This endpoint retrieves the team object. shell Copy curl \"{{API_URL}}/api/v1/teams/TI73TDU19W48J/\" \\ --request GET \\ --header \"Authorization: meowmeowmeow\" \\ --header \"Content-Type: application/json\" \\ --header \"X-Grafana-URL: https://your-stack.grafana.net\" The above command returns JSON structured in the following way:" --- # Grafana OnCall teams HTTP API ## Get a team **Required permission**: `grafana-irm-app.user-settings:read` This endpoint retrieves the team object. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/teams/TI73TDU19W48J/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "id": "TI73TDU19W48J", "grafana_id": 123, "name": "my test team", "email": "", "avatar_url": "/avatar/3f49c15916554246daa714b9bd0ee398" } ``` **HTTP request** `GET {{API_URL}}/api/v1/teams//` Expand table | Parameter | Unique | Description | |--------------|---------|--------------------------------| | `id` | Yes/org | OnCall team ID | | `grafana_id` | Yes/org | Grafana team ID | | `name` | Yes/org | Team name | | `email` | Yes/org | Team e-mail | | `avatar_url` | Yes | Avatar URL of the Grafana team | ## Get current on-call users for a team **Required permission**: `grafana-irm-app.user-settings:read` Returns the users currently on-call for a team by resolving the team’s direct paging integration. By default, the **default route** is used. Pass a `route` query parameter to resolve a specific route instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/teams/TI73TDU19W48J/current_oncall/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "count": 1, "users": [ { "id": "U4DNY931HHJS5", "grafana_id": 456, "email": "alice@example.com", "slack": { "user_id": "UALICESLACKID", "team_id": "TSLACKTEAMID" }, "username": "alice", "role": "admin", "is_phone_number_verified": true, "phone_number": "+12345678901", "phone_number_status": "available", "timezone": "America/New_York", "teams": ["TAAM1K1NNEHAG"] } ], "shifts": [ { "schedule_id": "SBM7DV7BKFUYU", "schedule_name": "Primary Rotation", "team_id": "TI73TDU19W48J", "shift_start": "2026-03-24T09:00:00+00:00", "shift_end": "2026-03-25T09:00:00+00:00", "users": ["U4DNY931HHJS5"] } ] } ``` Expand table | Parameter | Description | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `slack` | A Slack user identity (`user_id`, `team_id`), or `null` if not connected. | | `timezone` | The user’s timezone (e.g. `America/New_York`), or `null`. | | `teams` | List of team IDs the user belongs to. | | `phone_number` | The user’s verified phone number, or `null` if not configured or private. | | `phone_number_status` | One of: `available` (number returned), `private` (user has hidden their number), `not_configured` (user has no verified number). | | `shifts` | List of shift entries with schedule reference (`schedule_id`, `schedule_name`, `team_id`) and timing (`shift_start`, `shift_end`). Empty when resolution is not schedule-based. | When the team has no direct paging integration or no one is currently on-call, `count` is `0`, `users` is an empty list, and `shifts` is an empty list. **HTTP request** `GET {{API_URL}}/api/v1/teams//current_oncall/` Expand table | Query Parameter | Required | Default | Description | |-----------------|----------|---------|------------------------------------------------------------------------------------------------------------------------| | `route` | No | — | Route ID (public primary key) to resolve. If omitted, the default route is used. Obtain route IDs from the Routes API. | ## Get previous on-call users for a team **Required permission**: `grafana-irm-app.user-settings:read` Returns the users who were on-call during the most recently completed shift for the team’s direct paging integration schedule(s). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/teams/TI73TDU19W48J/previous_oncall/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The response format is identical to `current_oncall`. The `shifts` array contains the most recently ended shift(s). Expand table | Query Parameter | Required | Default | Description | |-----------------|----------|---------|------------------------------------------------------------------------------------------------------------------------| | `days` | No | `7` | Number of days to look back for past shifts. Maximum value: 30. | | `route` | No | — | Route ID (public primary key) to resolve. If omitted, the default route is used. Obtain route IDs from the Routes API. | **HTTP request** `GET {{API_URL}}/api/v1/teams//previous_oncall/` ## Get next on-call users for a team **Required permission**: `grafana-irm-app.user-settings:read` Returns the users who will be on-call during the next upcoming shift for the team’s direct paging integration schedule(s). Shifts that overlap with the current time are skipped. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/teams/TI73TDU19W48J/next_oncall/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The response format is identical to `current_oncall`. The `shifts` array contains the next upcoming shift(s). Expand table | Query Parameter | Required | Default | Description | |-----------------|----------|---------|------------------------------------------------------------------------------------------------------------------------| | `days` | No | `7` | Number of days to look ahead for future shifts. Maximum value: 30. | | `route` | No | — | Route ID (public primary key) to resolve. If omitted, the default route is used. Obtain route IDs from the Routes API. | **HTTP request** `GET {{API_URL}}/api/v1/teams//next_oncall/` ## List Teams **Required permission**: `grafana-irm-app.user-settings:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/teams/" \ --request GET \ --header "Authorization: meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": "TI73TDU19W48J", "grafana_id": 123, "name": "my test team", "email": "", "avatar_url": "/avatar/3f49c15916554246daa714b9bd0ee398" } ], "page_size": 50, "current_page_number": 1, "total_pages": 1 } ``` > **Note**: The response is [paginated](/docs/grafana-cloud/alerting-and-irm/irm/reference/oncall-api/#pagination). You may need to make multiple requests to get all records. The following available filter parameter should be provided as a `GET` argument: - `name` (Exact match) **HTTP request** `GET {{API_URL}}/api/v1/teams/`