---
title: "Get role by ID"
method: GET
path: "/rbac/roles/{id}"
tags: ["rbac"]
---

# Get role by ID

`GET /rbac/roles/{id}`

## Request

- Base URL: `https://api.axiom.co/v2`
- URL: `https://api.axiom.co/v2/rbac/roles/{id}`
- Auth: OAuth 2
  - Authorization code: `https://accounts.google.com/o/oauth2/v2/auth`
  - Token URL: `https://www.googleapis.com/oauth2/v4/token` scopes: `rbac|read`
- TypeScript: <https://skmtc.dev/axiom/apis/axiom-public-api/docs/rbac/roles/:id/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves a custom role by ID with its capabilities and the IDs of users assigned the role directly. Built-in role IDs such as `axiom-admin` return `404`.

## Path parameters

- `id` string, required

## Response `200`

The role.

- RoleWithID: Defines a role and its associated permissions within the system
  - `datasetCapabilities` RoleDatasetCapabilities: Defines the available permissions for dataset operations
  - `description` string: Detailed description of the role's purpose and scope
  - `members` string[]: IDs of users assigned this role directly. Returned in responses and ignored in requests. To assign a role to a user, use the Update user role endpoint.
  - `name` string, required: Unique name identifier for the role
  - `orgCapabilities` RoleOrgCapabilities: Defines organization-wide permissions and capabilities
    - `annotations` string[]: Controls the management of annotations across the organization
    - `apiTokens` string[]: Controls the management of API tokens for authentication
    - `auditLog` string[]: Controls access to organization audit logs
    - `billing` string[]: Controls access to billing information and settings
    - `dashboards` string[]: Controls the management of organization dashboards
    - `datasets` string[]: Controls the management of organization datasets
    - `endpoints` string[]: Controls the management of API endpoints
    - `integrations` string[]: Controls the management of third-party integrations
    - `labels` string[]: Controls the management of labels
    - `monitors` string[]: Controls the management of monitoring
    - `notifiers` string[]: Controls the management of notification settings
    - `rbac` string[]: Controls access to role-based access control settings
    - `sharedAccessKeys` string[]: Controls the management of shared access keys
    - `users` string[]: Controls user management within the organization
    - `views` string[]: Controls the management of data views
  - `viewCapabilities` RoleViewCapabilities: Defines the available permissions for view operations
  - `id` string, required: Unique identifier for the role

## Other responses

- `404`: Not found

## Changes

- **2026-10-16** (v2) `fbc1b8430feb`: 1 info
  - added the non-success response with the status `404`
- **2026-10-14** (v2) `8920e1697284`: 2 warning, 1 info
  - removed the optional property `allOf[#/components/schemas/Role]/datasetCapabilities/additionalProperties/data` from the response with the `200` status
  - removed the optional property `allOf[#/components/schemas/Role]/orgCapabilities/flows` from the response with the `200` status
  - added the optional property `allOf[#/components/schemas/Role]/orgCapabilities/labels` to the response with the `200` status

[Operation history](https://skmtc.dev/axiom/apis/axiom-public-api/changes/rbac/roles/:id/get.md)

---

[API](https://skmtc.dev/axiom/apis/axiom-public-api.md) - [All operations](https://skmtc.dev/axiom/apis/axiom-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axiom/apis/axiom-public-api/revisions/7e39a295e3ba?raw)