# List trainees

`GET https://api.coach-platform.com/api/public/trainees`

List trainees of the coach, filterable by label/search.

- Resource: Trainees
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/get-trainees
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | string | No | Page number (1-based, default 1) |
| `limit` | string | No | Items per page (1-500, default 25) |
| `search` | string | No | Search by name, email, or phone |
| `labelId` | string | No | Filter to trainees with this label |
| `email` | string | No | Match by email (case insensitive) |
| `phone` | string | No | Match by phone number |
| `status` | string | No | Filter by coaching status. "active" = has an active coaching period. "pending" = invited but not yet approved by the coach; these trainees are not returned by the other filters, and their activeCoachDetails.pendingCoachDate tells you how long they have been waiting. "archived" = removed with DELETE /trainees/{traineeId}; they are excluded from every other filter and from GET /trainees/{traineeId}, which answers 403 for them, so this is the only way to see them. Archived results carry no activeCoachDetails, and support only page, limit, search, email and phone. Bring one back with POST /trainees/{traineeId}/restore. Allowed values: `active`, `inactive`, `pending`, `archived`. |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object[] |   |
| `data[].id` | string |   |
| `data[].name` | string |   |
| `data[].email` | string |   |
| `data[].phoneNumber` | string |   |
| `data[].goal` | string |   |
| `data[].profileImageUrl` | string |   |
| `data[].personalDetails` | object |   |
| `data[].labels` | object[] |   |
| `data[].labels[].id` | string |   |
| `data[].labels[].text` | string |   |
| `data[].labels[].color` | string |   |
| `data[].labels[].coachId` | string |   |
| `data[].assignedEmployees` | object[] |   |
| `data[].assignedEmployees[].id` | string |   |
| `data[].assignedEmployees[].name` | string |   |
| `data[].activeCoachDetails` | object |   |
| `data[].activeCoachDetails.activeEscort` | string \| null | Id of the escort currently in use for this trainee. Fetch the full escort with GET /escorts/{escortId}. |
| `data[].activeCoachDetails.pendingCoach` | string \| null | Coach id this trainee is pending approval for. Set when the trainee was invited but has not been approved yet; null once approved. Use ?status=pending on GET /trainees to list only these. |
| `data[].activeCoachDetails.pendingCoachDate` | string<date-time> \| null | When the trainee entered the pending state. Use it to measure how long approval has been waiting. |
| `data[].createdAt` | string<date-time> |   |
| `pagination` | object |   |
| `pagination.page` | number |   |
| `pagination.limit` | number |   |
| `pagination.total` | number \| null | Total number of matching items. null when the underlying source cannot report an exact count for this page; use hasMore to keep paging. |
| `pagination.hasMore` | boolean |   |
| `pagination.truncated` | boolean | Present and true when the result set exceeded the in-memory scan cap and was truncated. Narrow your filters to page through all items. |

Example:

```json
{
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "goal": "<string>",
      "profileImageUrl": "<string>",
      "personalDetails": {},
      "labels": [
        {
          "id": "<string>",
          "text": "<string>",
          "color": "<string>",
          "coachId": "<string>"
        }
      ],
      "assignedEmployees": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ],
      "activeCoachDetails": {
        "activeEscort": "<string>",
        "pendingCoach": "<string>",
        "pendingCoachDate": "<date-time>"
      },
      "createdAt": "<date-time>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "hasMore": true,
    "truncated": true
  }
}
```

### Error responses 400, 401, 403, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request GET \
  --url 'https://api.coach-platform.com/api/public/trainees' \
  --header 'Authorization: Bearer cp_live_...'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/trainees', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer cp_live_...',
  },
});

const data = await response.json();
```

## Related endpoints

- [Create a trainee](https://www.coach-platform.com/docs/api/reference/post-trainees/index.md): `POST /api/public/trainees`. Create a new trainee for the coach.
- [Approve or reject pending trainees](https://www.coach-platform.com/docs/api/reference/post-trainees-pending/index.md): `POST /api/public/trainees/pending`. Approve or reject trainees from the coach's approval queue, which GET /trainees?status=pending lists.
- [Get a trainee](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id/index.md): `GET /api/public/trainees/{traineeId}`. Get a single trainee by id.
- [Update a trainee](https://www.coach-platform.com/docs/api/reference/patch-trainees-trainee-id/index.md): `PATCH /api/public/trainees/{traineeId}`. Update a trainee's personal details.
- [Remove a trainee](https://www.coach-platform.com/docs/api/reference/delete-trainees-trainee-id/index.md): `DELETE /api/public/trainees/{traineeId}`. Remove a trainee from the coach account.
- [Restore an archived trainee](https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-restore/index.md): `POST /api/public/trainees/{traineeId}/restore`. Bring a trainee back from the archive, exactly as the dashboard does it.
- [Send access details to a trainee](https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-send-credentials/index.md): `POST /api/public/trainees/{traineeId}/send-credentials`. Send the trainee their app access details by email, and optionally by WhatsApp.
- [Get a trainee's weekly activity](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-weekly-activity/index.md): `GET /api/public/trainees/{traineeId}/weekly-activity`. Day-by-day activity for the week containing the given date (workouts, cardio, nutrition logging, water, measurements, form submissions).
- [Get a trainee's body measurements](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-measurements/index.md): `GET /api/public/trainees/{traineeId}/measurements`. A trainee's body measurements: weight history, body-fat history, circumference history, and custom measurement types.
- [Record a weigh-in](https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-body-metrics/index.md): `POST /api/public/trainees/{traineeId}/body-metrics`. Record a weigh-in for a trainee: weight, body fat, and/or body measurements.
- [List a trainee's progress photos](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-photos/index.md): `GET /api/public/trainees/{traineeId}/photos`. A trainee's progress photos as temporary viewable image URLs (valid a few minutes).
- [List a trainee's personal records](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-personal-records/index.md): `GET /api/public/trainees/{traineeId}/personal-records`. A trainee's personal records per exercise: best weight, estimated 1RM, top-set reps, max reps, set and total volume, and max duration, each with the value achieved, the previous record and when it was set.
- Previous: [Get the authenticated coach profile](https://www.coach-platform.com/docs/api/reference/get-me/index.md): `GET /api/public/me`. Returns the authenticated coach profile (name, email, plan limits).
- Next: [Create a trainee](https://www.coach-platform.com/docs/api/reference/post-trainees/index.md): `POST /api/public/trainees`. Create a new trainee for the coach.