# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.retainful.com/developers/lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.