# List Lists

`GET https://api.getprospect.com/v2/lists`

The workspace's people and company lists, most recently updated first unless `sort_by` names a column. Filter by `type`, `owner` (`me` or a user id) and `query` (a case-insensitive substring of the name). `records_count` is what an export of the list would write. `metadata.sort_by` reports the order actually served: null when none was asked for, or when the workspace holds too many lists to order (the default order is served then). With `include_saved_views=true`, `metadata.saved_views` also reports the standing views (every saved person or company, and those saved without a list), one entry each, narrowed by `type`. Free: costs no credits.

## Authentication

Pass your API key in the `x-api-key` header.

## Query parameters

- `type` (enum, optional): Only lists of this kind. Omit for both. Allowed values: `people`, `companies`.
- `owner` (string, optional, max length: 64): Whose lists. `me` for the caller's own, or a user id. Omit for everyone in the workspace.
- `query` (string, optional, max length: 100): Case-insensitive substring of the list name.
- `sort_by` (enum, optional): Order by this column. Omit for the default order, most recently updated first. `metadata.sort_by` reports the order actually served. Allowed values: `name`, `records_count`, `owner`, `created_at`, `updated_at`.
- `sort_direction` (enum, optional): Ignored without `sort_by`. Defaults to the column's own natural direction. Allowed values: `asc`, `desc`.
- `include_saved_views` (enum, optional): Also report the standing saved views - all saved people / companies, and those saved without a list - in `metadata.saved_views`: `{ type, saved, records_count, last_saved_at }` each. Honours `type`; ignores `owner`, `query` and paging. Off by default (four extra reads). Allowed values: `true`, `false`.
- `page` (integer, optional, min: 1, default: 1): The page, 1-based.
- `per_page` (integer, optional, min: 1, max: 100, default: 25): Lists per page.

## Example request

```bash
curl --request GET \
  --url https://api.getprospect.com/v2/lists \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Response 200

One page of lists.

```json
{
  "success": true,
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Q4 SaaS founders",
      "type": "people",
      "records_count": 128,
      "last_added_record_at": "2026-10-02T14:03:11.000Z",
      "created_at": "2026-09-28T09:12:44.000Z",
      "updated_at": "2026-10-02T14:03:11.000Z",
      "owner": {
        "id": "64f0c1d2e3f4a5b6c7d8e9f0",
        "first_name": "Dana",
        "last_name": "Reyes",
        "photo_url": null
      }
    }
  ],
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z",
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total_pages": 1,
      "total_count": 1
    },
    "sort_by": null,
    "sort_direction": null
  }
}
```

## Response 400

Invalid query (`VALIDATION_ERROR`; `payload.code` says which kind of mistake).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "per_page must not be greater than 100",
      "payload": {
        "field": "per_page",
        "code": "out_of_range",
        "received_value": 500,
        "received_type": "number",
        "constraints": {
          "max": "per_page must not be greater than 100"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 429

Over the `poll` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced for the caller channel.

## Response 500

Unexpected server error.