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

# List

The `list` method retrieves multiple records from a collection with support for filtering and pagination.

## Configuration Example

```yaml theme={null}
# spec.yml
name: Collection Name
methods:
  list:
    filterFields:
      - email
      - firstName
      - lastName
    parametersSchema:
      type: object
      properties:
        includeArchived:
          type: boolean
          default: false
```

Properties:

* **`parametersSchema`** (DataSchema): Schema for the additional parameters
* **`filterFields`** (array): Fields that can be used for filtering of the results.

## Implementation Examples

### REST API Mapping Implementation (Recommended)

**File:** `list.rest.yml`

```yaml theme={null}
path: /contacts
method: GET
requestMapping:
  query:
    limit: 100
    offset: { $var: $.cursor }
    email: { $var: $.filter.email }
    first_name: { $var: $.filter.firstName }
    last_name: { $var: $.filter.lastName }
    include_archived: { $var: $.parameters.includeArchived }
responseMapping:
  records: { $var: response.data.contacts }
  cursor: |
    {
      $cond: [
        { $var: response.data.hasMore },
        { $string: { $sum: [{ $number: { $var: $.cursor } }, 100] } },
        null
      ]
    }
```

### JavaScript Implementation

**File:** `list.js`

```javascript theme={null}
export default async function list({ apiClient, filter, cursor, parameters }) {
  const queryParams = {
    limit: 100,
    offset: cursor || 0,
    includeArchived: parameters?.includeArchived || false,
  }

  // Apply filters
  if (filter?.email) {
    queryParams.email = filter.email
  }
  if (filter?.firstName) {
    queryParams.first_name = filter.firstName
  }
  if (filter?.lastName) {
    queryParams.last_name = filter.lastName
  }

  const response = await apiClient.get('/contacts', { params: queryParams })

  return {
    records: response.data.contacts,
    cursor: response.data.hasMore ? String(queryParams.offset + 100) : undefined,
  }
}
```

## Input

| Property      | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| `filter`      | object | Filter criteria based on configured filterFields |
| `cursor`      | string | Pagination cursor from previous request          |
| `credentials` | object | Authentication credentials                       |
| `parameters`  | object | Method-specific parameters                       |

## Return Value

| Property     | Type   | Description                                           |
| ------------ | ------ | ----------------------------------------------------- |
| `records`    | array  | Array of records in API format (before fieldsFromApi) |
| `cursor`     | string | Cursor for next page (optional)                       |
| `drilldowns` | array  | Additional requests to fetch related data (optional)  |

## Drilldowns

The list method supports drilldowns for fetching nested or related data. This is useful for scenarios like fetching files from multiple folders or tasks across different projects.

```javascript theme={null}
// Example: Fetching files from folders
module.exports = async ({ filter, cursor, parameters }) => {
  if (!cursor && filter?.parentFolderId === 'root') {
    // First, get all folders
    const folders = await makeApiRequest({
      method: 'GET',
      path: '/api/folders',
      credentials,
    })

    // Return folders with drilldowns for their files
    return {
      records: folders.data,
      drilldowns: folders.data.map((folder) => ({
        parameters: { recursive: true },
        filter: {
          type: 'file',
          parentFolderId: folder.id,
        },
      })),
    }
  }

  // Regular file listing
  const response = await makeApiRequest({
    method: 'GET',
    path: '/api/files',
    query: { folderId: filter?.parentFolderId },
    credentials,
  })

  return {
    records: response.data,
  }
}
```

### Drilldown Structure

```json theme={null}
{
  "drilldowns": [
    {
      "parameters": { "recursive": true },
      "filter": {
        "type": "file",
        "parentFolderId": "123"
      }
    }
  ]
}
```