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

# List Target Lists

> Retrieve a paginated list of Target Lists in your workspace.

Retrieve Target Lists belonging to the workspace associated with your API key. A Target List contains Buyers and has one associated workflow.

```text theme={null}
GET /v1/target-lists
```

## Authentication

All requests require a workspace API key:

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

The examples use `$API_KEY` for your API key. The key determines the workspace; you do not supply a workspace ID. See [Authentication](https://docs.1eye.ai/api-reference/auth.md).

## Request

```bash theme={null}
curl "https://api.1eye.ai/v1/target-lists?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

## Query parameters

| Parameter | Type | Description |
| - | - | - |
| `limit` | integer | Number of Target Lists to return. Default: `100`. |
| `cursor` | string | Opaque cursor from the previous page. |

## Response

**200 OK**

```json theme={null}
{
  "total": 1,
  "data": [
    {
      "id": "lis_123456789012345678",
      "client_id": "wor_123456789012345678",
      "workflow_id": "lwo_123456789012345678",
      "workflow_status": "running",
      "name": "High-Intent Data Buyers",
      "description": "Buyers researching cloud data warehousing, lakehouse analytics, and enterprise AI infrastructure.",
      "buyer_count": 20,
      "created_by": {
        "id": "usr_123456789012345678",
        "type": "admin",
        "name": "Jane Doe",
        "profile_pic": "https://example.com/photo.jpg",
        "title": "Revenue Operations"
      },
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-20T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

All names, domains, identifiers, amounts, URLs, and timestamps in these examples are illustrative.

`total` is the number of available Target Lists, not the number of Buyers. Each item is a [Target List object](https://docs.1eye.ai/api-reference/retrieve-a-target-list.md).

## Pagination

Pass `pagination.next_cursor` as `cursor` for the next page. Continue until `next_cursor` is `null`. Do not construct or modify cursors.

```bash theme={null}
curl "https://api.1eye.ai/v1/target-lists?limit=100&cursor=YOUR_CURSOR" \
  -H "Authorization: Bearer $API_KEY"
```

An empty collection returns `data: []`, `total: 0`, and `pagination.next_cursor: null`. See [Pagination](https://docs.1eye.ai/api-reference/pagination.md).

## Behavior

* Returns only Target Lists accessible to the authenticated workspace.
* Includes the associated workflow ID and its current execution status.
* `buyer_count` counts distinct accessible Buyers currently in the list.
* Buyer records and workflow definitions are not embedded in the response.
* Listing does not create a list, run a workflow, trigger enrichment, or consume additional credits.

To retrieve Buyers in a list, use [Search Buyers](https://docs.1eye.ai/api-reference/search-buyers.md) with a `target_list_id` rule.

## Errors

| Status | Error code | Description |
| - | - | - |
| 400 | `invalid_parameter` | A request field or query parameter is invalid. |
| 400 | `invalid_cursor` | The cursor is invalid or does not match the request. |
| 401 | `authentication_error` | The API key is missing, invalid, or revoked. |
| 403 | `permission_denied` | The key does not have permission for this operation. |
| 429 | `rate_limit_exceeded` | The workspace API rate limit was exceeded. |
| 500 | `internal_error` | An unexpected server error occurred. |
| 503 | `service_unavailable` | The service is temporarily unavailable. |

Errors use the standard [error envelope](https://docs.1eye.ai/api-reference/errors.md). Use `request_id` when contacting support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.