---
title: "List custom roles"
method: GET
path: "/api/v2/roles"
tags: ["Custom roles"]
---

# List custom roles

`GET /api/v2/roles`

Get a complete list of custom roles. This includes project and organization roles that you create, or that are provided as presets by LaunchDarkly. It does not include base roles.

## Query parameters

- `limit` integer — The maximum number of custom roles to return. Defaults to 20.
- `offset` integer — Where to start in the list. Defaults to 0. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query `limit`.

## Response `200`

Custom roles collection response

- CustomRoles
  - `_links` object — The location and content type of related resources
  - `items` CustomRole[], required — An array of custom roles
    - `_id` string, required — The ID of the custom role
    - `_links` object, required — The location and content type of related resources
    - `_access` Access
      - `denied` AccessDenied[], required
        - `action` string, required
        - `reason` AccessDeniedReason, required
          - `resources` string[] — Resource specifier strings
          - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
          - `actions` ActionSpecifier[] — Actions to perform on a resource
          - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
          - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
          - `role_name` string
      - `allowed` AccessAllowedRep[], required
        - `action` string, required
        - `reason` AccessAllowedReason, required
          - `resources` string[] — Resource specifier strings
          - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
          - `actions` ActionSpecifier[] — Actions to perform on a resource
          - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
          - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
          - `role_name` string
    - `description` string — The description of the custom role
    - `key` string, required — The key of the custom role
    - `name` string, required — The name of the custom role
    - `policy` Statement[], required — An array of the policies that comprise this custom role
      - `resources` string[] — Resource specifier strings
      - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
      - `actions` ActionSpecifier[] — Actions to perform on a resource
      - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
      - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
    - `basePermissions` string
    - `resourceCategory` string
    - `assignedTo` AssignedToRep
      - `membersCount` integer — The number of individual members this role is assigned to
      - `teamsCount` integer — The number of teams this role is assigned to
    - `_presetBundleVersion` integer — If created from a preset, the preset bundle version
    - `_presetStatements` Statement[] — If created from a preset, the read-only statements copied from the preset
      - `resources` string[] — Resource specifier strings
      - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
      - `actions` ActionSpecifier[] — Actions to perform on a resource
      - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
      - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
  - `totalCount` integer — The total number of custom roles

## Other responses

- `401` — Invalid access token
- `403` — Forbidden
- `429` — Rate limited

---

[API](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api.md) · [All operations](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/launchdarkly/launchdarkly-rest-api/revisions/69c5c9aafe78/schema)