# List Roles

Returns paginated list of defined roles used in shaping resource plans, typically categorized by department and used to match people to work.

Endpoint: GET /v1/roles
Version: v1
Security: ApiKey

## Query parameters:

  - `page` (integer)
    The specific page of results requested.

  - `page_size` (integer)
    The number of results in each page.

  - `archived` (boolean)
    Indicates if results should be filtered by their archived status.

## Response 200 fields (application/json):

  - `count` (integer)
    The number of results in the current page.

  - `total` (integer)
    The total number of results that fulfill the request.

  - `page` (integer)
    The current page of results being returned.

  - `total_pages` (integer)
    The total number of available pages that fulfill the request.

  - `page_size` (integer)
    The number of results in each page returned.

  - `results` (array, required)
    The array of result objects for the current page.

  - `results.id` (string)
    The unique identifier for the Role in Parallax.

  - `results.name` (string)
    The name of the Role, typically describing the job function or skill set (e.g. Designer, Developer).

  - `results.department_id` (string)
    The unique identifier of the Department that this Role belongs to for capacity and reporting segmentation.

  - `results.capacity` (number)
    The full-time capacity for this Role, expressed as a percentage (e.g. 1.0 = 100%).

  - `results.billable_utilization_target` (number)
    The target percentage of billable utilization expected for this Role, expressed as a percentage (e.g. 1.0 = 100%).

  - `results.archived` (boolean)
    Indicates whether this Role has been archived and is no longer active for planning or reporting.

  - `results.created_date` (string)
    The date and time when the Role record was created in Parallax.

  - `results.modified_date` (string)
    The date and time when the Role record was last modified in Parallax.

## Response 400 fields (application/json):

  - `type` (string)
    RFC reference for the error type

  - `title` (string)
    Human-readable summary of the error

  - `status` (integer)
    HTTP status code

  - `errors` (array)
    Detailed error messages for each validation failure

  - `trace_id` (string)
    Trace identifier for debugging