> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruddr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Endpoints

> Pagination, sorting, and filtering for list endpoints

All list endpoints in the Ruddr API use cursor-based pagination and return results in a common response format.

## Response Format

List endpoints return a wrapper object:

```json theme={null}
{
  "results": [
    { "id": "...", "createdAt": "2024-01-15T10:30:00.000Z", ... },
    { "id": "...", "createdAt": "2024-01-14T09:00:00.000Z", ... }
  ],
  "hasMore": true
}
```

| Field     | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| `results` | array   | Array of resource objects                                 |
| `hasMore` | boolean | Whether additional pages exist in the traversal direction |

## Pagination

### Query Parameters

| Parameter       | Type    | Default | Description                                                       |
| --------------- | ------- | ------- | ----------------------------------------------------------------- |
| `startingAfter` | UUID    | —       | Cursor ID from the previous response to request the next page     |
| `endingBefore`  | UUID    | —       | Cursor ID from the previous response to request the previous page |
| `limit`         | integer | `10`    | Maximum number of results to return (`1`–`100`)                   |

<Note>
  `startingAfter` and `endingBefore` are mutually exclusive — only one can be used per request. Omitting both returns
  results from the beginning.
</Note>

### Iterating Through Pages

To fetch all results, use the `id` of the last item in each response as the `startingAfter` cursor for the next request. Continue until `hasMore` is `false`.

**First page:**

```bash theme={null}
curl "https://www.ruddr.io/api/workspace/clients?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Next page** (using the last `id` from the previous response):

```bash theme={null}
curl "https://www.ruddr.io/api/workspace/clients?limit=10&startingAfter=LAST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Previous page** (using the first `id` from the current response):

```bash theme={null}
curl "https://www.ruddr.io/api/workspace/clients?limit=10&endingBefore=FIRST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Sorting

All list endpoints return results sorted by `createdAt` in descending order (newest first). The sort order is not configurable — there are no `sort` or `orderBy` parameters.

## Filtering

Most list endpoints accept query parameters to narrow results. Available filters vary by endpoint and are documented in the [API Reference](/api-reference/clients/list-clients).

### Filter Types

| Type            | Convention                                                            | Example                                         |
| --------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| UUID            | Field name (e.g., `clientId`)                                         | `?clientId=<uuid>`                              |
| Exact string    | Field name (e.g., `code`)                                             | `?code=PRJ-001`                                 |
| String matching | `field`, `fieldContains`, `fieldStartsWith`, `fieldEndsWith`          | `?nameContains=Acme`                            |
| Date range      | `field`, `fieldAfter`, `fieldOnAfter`, `fieldBefore`, `fieldOnBefore` | `?dateOnAfter=2025-01-01&dateBefore=2025-02-01` |
| Enum            | Field name (e.g., `statusId`)                                         | `?statusId=active`                              |

<Note>String matching filters are case-insensitive. Date filters use `YYYY-MM-DD` format.</Note>

### Example

Fetch the first page of active projects for a specific client:

```bash theme={null}
curl "https://www.ruddr.io/api/workspace/projects?clientId=CLIENT_ID&statusId=active&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Combine filtering with pagination to iterate through the results:

```bash theme={null}
curl "https://www.ruddr.io/api/workspace/projects?clientId=CLIENT_ID&statusId=active&limit=25&startingAfter=LAST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```