> ## Documentation Index
> Fetch the complete documentation index at: https://guides.affiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/products/lists — retrieve your product lists

> Retrieve all product lists for your API key. Filter by metadata key:value pairs to find specific lists. Returns list summaries, not full product data.

Use `GET /v1/products/lists` to retrieve all product lists associated with your API key. You can optionally filter the results by one or more metadata key:value pairs. The response includes list summaries — name, `products_count`, and metadata — but not the individual product details.

<Note>
  This endpoint returns list summaries only. It does **not** return the products inside each list. To retrieve full product data for a specific list, use [GET /v1/products/lists/{list_id}](/api-reference/lists/get-list).
</Note>

## Request

**Endpoint:** `GET /v1/products/lists`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number for paginating through results.
</ParamField>

<ParamField query="per_page" type="integer" default="100">
  Number of lists to return per page.
</ParamField>

<ParamField query="metadata[{key}]" type="string">
  Filter lists by a metadata key:value pair. Repeat for multiple filters. Only lists that match **all** specified pairs are returned.

  ```
  ?metadata[category]=tech_products&metadata[campaign]=summer
  ```
</ParamField>

## Example requests

<CodeGroup>
  ```bash All lists theme={null}
  curl --request GET \
    --url 'https://api.affiliate.com/v1/products/lists' \
    --header 'Authorization: Bearer {your_api_key}'
  ```

  ```bash Filter by metadata theme={null}
  curl --request GET \
    --url 'https://api.affiliate.com/v1/products/lists?metadata[category]=tech_products&metadata[campaign]=summer' \
    --header 'Authorization: Bearer {your_api_key}'
  ```
</CodeGroup>

## Response

A `200 OK` response contains a paginated `data` array of list summary objects and a `meta` object with pagination details.

```json theme={null}
{
  "meta": {
    "total": 3,
    "from": 1,
    "to": 3,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "019643ea-b78c-704e-b616-d67cfdbcbc2f"
  },
  "data": [
    {
      "id": "9ea4894b-8491-4a79-9419-902b69f70bed",
      "name": "listnamehere",
      "metadata": {
        "key1": "metavalueiwantreturned"
      },
      "products_count": 2,
      "product_ids": [
        "8099982740095203709",
        "8099987467386791069"
      ],
      "products": [
        {
          "id": "8099982740095203709",
          "name": "Acrylic Bubblegum Tupac by N Perez Print",
          "image_url": "https://assets.wfcdn.com/im/96908466/resize-h400-w400%5Ecompr-r85/7745/77458008/.jpg"
        },
        {
          "id": "8099987467386791069",
          "name": "Bubblegum Tupac by N Perez - Round Photograph",
          "image_url": "https://assets.wfcdn.com/im/08259379/resize-h400-w400%5Ecompr-r85/7745/77458009/.jpg"
        }
      ]
    }
  ]
}
```

### Response fields

<ResponseField name="meta" type="object">
  Pagination and request metadata.

  <Expandable title="meta properties">
    <ResponseField name="meta.total" type="integer">
      Total number of lists matching the query.
    </ResponseField>

    <ResponseField name="meta.from" type="integer">
      Index of the first result on this page.
    </ResponseField>

    <ResponseField name="meta.to" type="integer">
      Index of the last result on this page.
    </ResponseField>

    <ResponseField name="meta.current_page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="meta.last_page" type="integer">
      Last available page number.
    </ResponseField>

    <ResponseField name="meta.per_page" type="integer">
      Number of results per page.
    </ResponseField>

    <ResponseField name="meta.fields" type="array">
      Fields included in the response. Empty array means all fields are returned.
    </ResponseField>

    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  Array of list summary objects.

  <Expandable title="data item properties">
    <ResponseField name="data[].id" type="string">
      Unique list identifier.
    </ResponseField>

    <ResponseField name="data[].name" type="string">
      List display name.
    </ResponseField>

    <ResponseField name="data[].metadata" type="object">
      Key:value metadata pairs associated with this list.
    </ResponseField>

    <ResponseField name="data[].products_count" type="integer">
      Number of products in the list.
    </ResponseField>

    <ResponseField name="data[].product_ids" type="string[]">
      Array of product ID strings stored in the list.
    </ResponseField>

    <ResponseField name="data[].products" type="array">
      Lightweight product previews — each contains `id`, `name`, and `image_url` only. To get full product details, use [GET /v1/products/lists/{list_id}](/api-reference/lists/get-list).
    </ResponseField>
  </Expandable>
</ResponseField>