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

# GET /taxonomy/attributes/{handle}/values — list an attribute's values

> List one taxonomy attribute's canonical value handles and display labels, ready to send as search facet values.

`GET /taxonomy/attributes/{handle}/values` lists the canonical values of one attribute, such as `neckline__halter` for `neckline`. To filter search by a value, send `{"name": attribute.facetName, "values": [value.handle]}` in `facets` on [`POST /products/search`](https://storerouter.ai/docs/api-reference/search-products).

> [!NOTE]
>
> These are canonical definitions, not inventory. A value listed here may match no product in your catalog scope. Use [`POST /products/facet-counts`](https://storerouter.ai/docs/api-reference/count-product-facets) with `attributes` to list only values that have products, with counts.

This endpoint is not billed. It is rate limited like every `/v1` route.

## Request

```bash theme={null}
curl "https://api.storerouter.ai/v1/taxonomy/attributes/neckline/values?limit=3" \
  -H "Authorization: Bearer $STOREROUTER_API_KEY"
```

### Path parameters

**handle** `string` *required*

Attribute handle from [`GET /taxonomy/attributes`](https://storerouter.ai/docs/api-reference/list-taxonomy-attributes), such as `neckline`.

### Query parameters

**offset** `integer` (default: 0)

Number of values to skip. Use the previous page's `nextOffset`.

**limit** `integer` (default: 50)

Values per page, from 1 to 100.

## Response

**taxonomyVersion** `string` *required*

Canonical taxonomy version name, such as `v4`.

**attribute** `TaxonomyAttribute` *required*

The attribute, in the shape [`GET /taxonomy/attributes`](https://storerouter.ai/docs/api-reference/list-taxonomy-attributes#response) returns. Its `facetName` is the facet to send the value handles under.

**values** `TaxonomyAttributeValue[]` *required*

This page of values.

**TaxonomyAttributeValue properties**

**handle** `string` *required*

Canonical value handle, such as `neckline__halter`. Send it unchanged in the attribute facet's `values`.

**name** `string` *required*

Display label, such as `Halter`.

**total** `integer` *required*

Number of values across all pages.

**nextOffset** `integer | null` *required*

Offset of the next page. Repeat the request with it as `offset`. `null` on the last page.

### Example response

```json theme={null}
{
  "taxonomyVersion": "v4",
  "attribute": {
    "handle": "neckline",
    "name": "Neckline",
    "description": "Used to describe the neck shape of a garment, such as V-neck or boat",
    "facetName": "neckline",
    "matching": "any selected value; exact canonical handles",
    "valueCount": 26
  },
  "values": [
    {"handle": "neckline__asymmetric", "name": "Asymmetric"},
    {"handle": "neckline__boat", "name": "Boat"},
    {"handle": "neckline__collared", "name": "Collared"}
  ],
  "total": 26,
  "nextOffset": 3
}
```

To find boat-neck dresses, combine the category facets from [`GET /taxonomy/categories`](https://storerouter.ai/docs/api-reference/list-taxonomy-categories) with the attribute facet:

```json theme={null}
{
  "facets": [
    {"name": "category_path.depth_0", "values": ["apparel & accessories"]},
    {"name": "category_path.depth_1", "values": ["clothing"]},
    {"name": "category_path.depth_2", "values": ["dresses"]},
    {"name": "neckline", "values": ["neckline__boat"]}
  ]
}
```

## Errors

| Status | `detail` | Cause |
| - | - | - |
| `404` | `taxonomy_attribute_not_found` | `handle` names no attribute. |
| `422` | Validation array | `offset` or `limit` is out of range. |

See the [overview](https://storerouter.ai/docs/api-reference/overview.md#error-model) for authentication and rate-limit errors.

Operation ID: `listTaxonomyAttributeValues`. SDK methods: Python `list_taxonomy_attribute_values(handle, offset=..., limit=...)`; TypeScript `listTaxonomyAttributeValues(handle, { offset, limit })`. The MCP equivalent is [`taxonomy_attribute`](https://storerouter.ai/docs/mcp/overview#taxonomy-discovery-tools).


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