# Lists

Retrieves audience lists that you have set up in Retainful -> Audience -> Lists

### Endpoint

```
GET /v2/lists
```

### Query Parameters

| Parameter | Type   | Required? | Description                                                                                       |
| --------- | ------ | --------- | ------------------------------------------------------------------------------------------------- |
| `page`    | number | No        | The page of results to retrieve. Defaults to `1` if not specified.                                |
| `limit`   | number | No        | Number of items to retrieve per page. Defaults to a system setting if not specified (e.g., `25`). |

**Example**:

```
GET /v2/lists?page=2&limit=20
```

This returns the second page of results with 20 items per page.

***

### Example Request

```http
GET /v2/lists?page=1&limit=10
Host: apiv2.retainful.net
Retainful-Api-Key: YOUR_API_KEY
Retainful-App-Id: YOUR_APP_ID
```

No request body is required for this endpoint. The parameters are passed as query strings.

***

### Example Response (200 OK)

```json
{
  "success": true,
  "data": {
    "lists": [
      {
        "uuid": "5Wce8EGvub9D7NCizYiE8qVGtNwbGMkzZVUL",
        "name": "Newsletter Subscribers",
        "created_at": 1740574233,
        "description": "This is a list of all newsletter subscribers"
      }
    ],
    "current_page": 1,
    "total_pages": 1,
    "total_items": 6,
    "items_per_page": 10
  }
}
```

#### Response Fields

| Field                 | Type             | Description                                                                       |
| --------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `success`             | boolean          | Indicates if the request was successful (`true`/`false`).                         |
| `data.lists`          | array of objects | Collection of list objects.                                                       |
| `lists[].uuid`        | string           | Unique identifier of the list.                                                    |
| `lists[].name`        | string           | The display name of the list.                                                     |
| `lists[].created_at`  | number (epoch)   | Unix timestamp (seconds since the epoch) for when the list was created.           |
| `lists[].description` | string           | Optional text describing the list’s purpose, content, or any other relevant info. |
| `data.current_page`   | number           | The current page number in the paginated results.                                 |
| `data.total_pages`    | number           | The total number of pages available given the current `limit`.                    |
| `data.total_items`    | number           | The total number of available lists.                                              |
| `data.items_per_page` | number           | Number of items per page.                                                         |

***

### Error Responses

* **401 Unauthorized**\
  Returned if the provided API key or App ID is missing or invalid.

  ```json
  {
    "status": "error",
    "message": "Unauthorized access. Invalid or missing credentials."
  }
  ```
* **400 Bad Request**\
  Returned if the `page` or `limit` parameters are invalid (e.g., negative numbers).

  ```json
  {
    "status": "error",
    "message": "Invalid 'page' or 'limit' parameter."
  }
  ```
* **500 Internal Server Error**\
  Returned if an unexpected error occurred on the server.

  ```json
  {
    "status": "error",
    "message": "An unexpected error occurred."
  }
  ```

***

### Best Practices & Notes

1. **Pagination Defaults**\
   If you do not specify `page` or `limit`, Retainful will use default values (e.g., page = 1, limit = 25).
2. **Efficient Data Handling**\
   For large datasets, paginate through results instead of trying to load everything in a single request.
3. **Keep Credentials Secure**\
   Always safeguard your `Retainful-Api-Key` and `Retainful-App-Id`. Never expose these in public or client-side code.
4. **Integrate Properly**\
   Use this list data to segment your contacts or display audiences in your application’s UI. Consistent referencing of list IDs is crucial for other Retainful endpoints.