---
title: "Grafana OnCall users HTTP API | Grafana Cloud documentation"
description: "Grafana OnCall users HTTP API Get a user Required permission: grafana-irm-app.user-settings:read This endpoint retrieves the user object. shell Copy curl \"{{API_URL}}/api/v1/users/current/\" \\ --request GET \\ --header \"Authorization: Bearer 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:"
---

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

# Grafana OnCall users HTTP API

## Get a user

**Required permission**: `grafana-irm-app.user-settings:read`

This endpoint retrieves the user object.

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
curl "{{API_URL}}/api/v1/users/current/" \
  --request GET \
  --header "Authorization: Bearer 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": "U4DNY931HHJS5",
  "grafana_id": 456,
  "email": "public-api-demo-user-1@grafana.com",
  "slack": {
      "user_id": "UALEXSLACKDJPK",
      "team_id": "TALEXSLACKDJPK"
  },
  "username": "alex",
  "role": "admin",
  "timezone": "UTC",
  "teams": [],
  "is_phone_number_verified": true,
  "phone_number": "+12345678901",
  "phone_number_status": "available"
}
```

**HTTP request**

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

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

Expand table

| Parameter                  | Unique  | Description                                                                                                                      |
|----------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------|
| `id`                       | Yes/org | OnCall user ID                                                                                                                   |
| `grafana_id`               | Yes/org | Grafana user ID                                                                                                                  |
| `email`                    | Yes/org | User e-mail                                                                                                                      |
| `slack`                    | Yes/org | User ID 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).                          |
| `teams`                    | No      | List of team IDs the user belongs to                                                                                             |
| `is_phone_number_verified` | No      | Whether the user has a verified phone number.                                                                                    |
| `phone_number`             | No      | The user’s verified phone number, or `null` if not configured or private.                                                        |
| `phone_number_status`      | No      | One of: `available` (number returned), `private` (user has hidden their number), `not_configured` (user has no verified number). |

> Note
> 
> When the organization setting **Override phone number privacy for API** is enabled, users who have set their phone number to private will still have their number returned with status `available`. This setting does not affect phone number visibility in the UI.

## List Users

**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/users/" \
  --request GET \
  --header "Authorization: Bearer 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": "U4DNY931HHJS5",
      "grafana_id": 456,
      "email": "public-api-demo-user-1@grafana.com",
      "slack": {
          "user_id": "UALEXSLACKDJPK",
          "team_id": "TALEXSLACKDJPK"
      },
      "username": "alex",
      "role": "admin",
      "timezone": "UTC",
      "teams": ["TAAM1K1NNEHAG"],
      "is_phone_number_verified": true,
      "phone_number": "+12345678901",
      "phone_number_status": "available"
    }
  ],
  "current_page_number": 1,
  "page_size": 100,
  "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:

- `username` (Exact match)
- `team_id` (Exact match, team ID)

**HTTP request**

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