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

# Retrieve a Target List

> Retrieve a Target List and its workflow metadata using its public ID.

Retrieve one Target List, including its workflow identity, execution state, creator, and Buyer count.

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

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

## Path parameter

| Parameter | Type | Description |
| - | - | - |
| `target_list_id` | string | Target List ID, beginning with `lis_`. |

## Request

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

## Response

**200 OK** — returns the Target List object directly.

```json theme={null}
{
  "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"
}
```

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

## Target List fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Public Target List ID (`lis_`). |
| `client_id` | string | Workspace ID (`wor_`). |
| `workflow_id` | string | Associated Target List Workflow ID (`lwo_`). |
| `workflow_status` | string | Current workflow execution state, for example `running` or `not_running`. |
| `name` | string | Target List name. |
| `description` | string | Target List description. |
| `buyer_count` | integer | Number of distinct accessible Buyers currently associated with the list. |
| `created_by` | object | Creator metadata: `id`, `type`, `name`, `profile_pic`, and `title`. |
| `created_at` | datetime | Creation timestamp in UTC. |
| `updated_at` | datetime | Last modification timestamp in UTC. |

The workflow is a separate resource. `workflow_status` describes its execution state, rather than a separate Target List lifecycle state. The response does not include workflow nodes or execution history.

`created_by.type` describes the creator's workspace role, such as `admin` or `marketer`.

## Retrieve Buyers from the Target List

Use the existing [Search Buyers](https://docs.1eye.ai/api-reference/search-buyers.md) endpoint with `target_list_id`:

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/buyers/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "target_list_id",
        "operator": "eq",
        "value": "lis_123456789012345678"
      }
    ]
  }
}'
```

Use the `in` operator with an array of list IDs to search multiple lists. Buyer Search returns canonical Buyer objects and supports combining list membership with other Buyer filters.

## Resource access and credits

Missing or inaccessible Target Lists return `404 not_found`. Retrieval is read-only and consumes no additional credits.

## Errors

| Status | Error code | Description |
| - | - | - |
| 400 | `invalid_parameter` | A request field or query parameter is invalid. |
| 404 | `not_found` | The Target List does not exist or is inaccessible to the workspace. |
| 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.