Documentation Grafana Cloud Observe and act Manage on-call and incidents Reference OnCall API OnCall users API

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:

JSON Copy

{
  "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.

List Users

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

shell Copy

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

{
  "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/

Verify a user’s phone number

Use this endpoint to set and verify another user’s phone number without a verification code. Because the endpoint bypasses phone ownership verification, confirm that the number belongs to the user before you submit the request. You can’t use this endpoint to verify your own number or assign a phone number to a service account.

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

This endpoint is available on paid plans. It isn’t available on Free or trial plans. For authentication options, refer to Authentication.

HTTP request: POST /api/v1/users/{user_id}/verify_phone_number/

For USER_ID, use the id returned by List users.

Send a JSON object with the following fields:

To set and verify a number using a service account token:

sh Copy

curl "<API_URL>/api/v1/users/<USER_ID>/verify_phone_number/" \
  --request POST \
  --header "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  --header "X-Grafana-URL: https://<STACK_SLUG>.grafana.net" \
  --header "Content-Type: application/json" \
  --data '{"phone_number": "+12025550123"}'

To approve replacing a different verified number, send this body to the same endpoint:

JSON Copy

{
  "phone_number": "+12025550124",
  "replace_existing": true
}

The request returns a response in the following format:

JSON Copy

{
  "id": "U4DNY931HHJS5",
  "status": "verified"
}

The status is verified when the number is newly verified or replaces a different number. It is unchanged when the user already has that number verified.

IRM attempts to send an SMS confirmation to the newly verified number. If you replace a number, IRM also attempts to send a disconnection message to the previous number. The number remains verified if either message can’t be delivered.

This endpoint allows 10 requests per minute per caller and 30 requests per minute per stack. Retries count toward these limits.

If a request times out, you can retry it with the same phone number. Repeating a successful request returns unchanged and doesn’t resend SMS messages.