# List roles

Page through roles (jobs) in a stable, curated shape. Scope: roles:read.

Lists roles (jobs) your key can see, in the stable v1 shape. **Scope:** `roles:read`. Visibility: admins all; employer-write members see their org's roles (confidential roles only if they're the HR rep or hiring manager); hiring managers see assigned roles.

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | 0-indexed page. Default `0`. |
| `pageSize` | integer | No | Rows per page (max 100). Default `20`. |
| `organizationId` | string | No | Filter to a single organization. |
| `status` | string | No | Filter by role status. |

## Example request

```bash
curl "https://app.talent-ray.com/api/v1/roles?status=open" \
  -H "Authorization: Bearer tr_YOUR_KEY"
```

## Response

`200 OK`

```json
{
  "data": [
    {
      "id": "role_eng_be",
      "name": "Senior Backend Engineer",
      "organizationId": "org_acme",
      "status": "open",
      "priority": "high",
      "isPublic": true,
      "department": "Engineering",
      "location": "Remote",
      "workType": "remote",
      "salaryMin": 90000,
      "salaryMax": 120000,
      "salaryCurrency": "EUR",
      "salaryPeriod": "year",
      "targetHireCount": 2,
      "roleLevel": "senior",
      "createdAt": "2026-05-01T09:00:00Z",
      "updatedAt": "2026-06-01T09:00:00Z"
    }
  ],
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 12, "totalPages": 1 }
}
```

## Status codes

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `401` | No valid API key. |
| `403` | `insufficient_scope` — the key lacks `roles:read`. |
| `429` | Rate limit exceeded. |