---
title: "Retrieve variations"
method: GET
path: "/v2/variations"
tags: ["Variations"]
---

# Retrieve variations

`GET /v2/variations`

**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `catalog(r)`.

Retrieve all item variations, optionally filtered by id(s).

## Query parameters

- `key` string, required — The key of the index to use.
- `section` string — The section of the index to use. Defaults to `Products`.
- `id` string[] — The ID(s) of the variations to return.
- `item_id` string[] — The item ID(s) of variations to return.
- `next_page_cursor` string — Pagination cursor from which to start returning results. Cannot be used together with `page` or `offset`.
- `num_results_per_page` integer — The number of results per page to return.
- `page` integer — The page of results to return.
- `offset` integer — The number of results to skip from the beginning. Cannot be used together with `page`.
- `c` string — The ID of the client and version that the request is coming from, such as `cio-js-2.90`.

## Response `200`

OK

- VariationListGetResponse
  - `total_count` integer — Total number of variations. Omitted when using cursor-based pagination (`next_page_cursor`).
  - `variations` VariationGetResponse[], required
    - `id` string, required — The ID of the variation, must be unique.
    - `item_id` string, required — The ID of the item this variation is attached to.
    - `name` string — The name of the variation, as it will appear in the results. Contains at least one alphanumeric character.
    - `suggested_score` integer — A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
    - `data` VariationMetadataResponse — Additional data about item. In addition to the listed properties you can also provide any other information you want to associate with that item. No special validation is made for that data.
      - `keywords` string[] — An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
      - `url` string — A URL to directly send the user after selecting the item. Might be required in some cases. Please contact support@constructor.io if you have questions around that.
      - `image_url` string — A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied).
      - `facets` Facets
      - `group_ids` string[] — You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
      - `description` string — A description for this item. The maximum length of this field is 4000 characters.
      - `active` boolean
      - `is_default` boolean — Whether this variation should always be returned as the best matching variation.
    - `updated_at` string, date-time, required — A date when the variation was updated.
  - `next_page_cursor` string — Pagination cursor to use to receive the next page of results. The value is returned by the previous page response. Cannot be used together with `page` or `offset`.

## Other responses

- `400` — Validation Error
- `401` — Credentials are not passed or action is forbidden.
- `403` — The supplied token does not have the required permissions.
- `429` — Rate limit breached

---

[API](https://skmtc.dev/constructor/apis/autocomplete.md) · [All operations](https://skmtc.dev/constructor/apis/autocomplete/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/constructor/autocomplete/revisions/2d33330633b6/schema)