Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Alerts and IRMbreadcrumb arrow IRMbreadcrumb arrow Referencebreadcrumb arrow OnCall APIbreadcrumb arrow OnCall users API
Grafana Cloud

Grafana OnCall users HTTP API

Get a user

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

This endpoint retrieves the user object.

shell 
curl "{{API_URL}}/api/v1/users/current/" \
  --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 
{
  "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.

ParameterUniqueDescription
idYes/orgOnCall user ID
grafana_idYes/orgGrafana user ID
emailYes/orgUser e-mail
slackYes/orgList of user IDs from connected Slack. User linking key is e-mail.
usernameYes/orgUser username
roleNoOne of: user, observer, admin.
timezoneNotimezone of the user one of time zones.
teamsNoList of team IDs the user belongs to
is_phone_number_verifiedNoWhether the user has a verified phone number.
phone_numberNoThe user’s verified phone number, or null if not configured or private.
phone_number_statusNoOne 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 
curl "{{API_URL}}/api/v1/users/" \
  --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 
{
  "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. 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/