---
title: "Retrieve refined queries"
method: GET
path: "/v1/refined_queries"
tags: ["Searchandising for Search"]
---

# Retrieve refined queries

`GET /v1/refined_queries`

**🔐 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: `facets.refined_queries(r)`, `searchandising.refined_queries(r)`.

Retrieve all refined queries.

## Query parameters

- `key` string, required — The key of the index to use.
- `response_section` 'results' | 'facets'
- `section` string — The section of the index to use. Defaults to `Products`.
- `query` string[] — A list of queries to filter by
- `phrase` string
- `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`.
- `sort_by` 'id' | 'created_at' | 'updated_at' | 'last_updated_internally' | 'last_updated_externally' — The attribute to sort by.
- `sort_order` 'ascending' | 'descending'
- `c` string — The ID of the client and version that the request is coming from, such as `cio-js-2.90`.

## Response `200`

OK

- RefinedQueryListGetResponse
  - `refined_queries` RefinedQueryResponse[], required
    - union
      - RefinedQueryResultsResponse
        - `id` integer, required
        - `query` string, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `last_updated_internally` string, date-time
        - `last_updated_externally` string, date-time
        - `last_reviewed_at` string, date-time
        - `last_reviewed_by` string
        - `next_review_at` string, date-time
        - `allow_automatic_rules` boolean, required
        - `slot_rules` SlotRuleResponse[], required
          - `request_filters` object — Facet conditions for the rule to be applied.
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` SlotRuleParameters, required
            - `item_id` string, required — The ID of an item to place in position.
            - `variation_slice` object — The variation slice ID of that item to use for slotting.
            - `position` integer, required — The position of item to place in.
            - `fuzzy_match` boolean — The flag to determine if the rule should be applied only when there's an exact query match. Warning: usage of this parameter has been deprecated - please contact Constructor support for assistance.
            - `labels` object — Can be used to add other miscellaneous properties for the item.
          - `rule_type` 'slot', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `variation_slicing_rule` VariationSlicingRuleResponse
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` VariationSlicingRuleParameters, required
            - `facet_names` string[], required — The facet which we will slice based on.
            - `filter_expression` union
              - …
          - `rule_type` 'variation_slicing', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `whitelist_rule` WhitelistRuleResponse
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` WhitelistFiltersRuleParameters, required
            - `filters` FiltersDict, required
          - `rule_type` 'whitelist', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `blacklist_rules` BlacklistRuleResponse[], required
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` ItemIdsOrFilters, required
            - `filters` FiltersDict
            - `item_ids` string[] — The IDs of the items to be recalled.
          - `rule_type` 'blacklist', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `boost_rules` BoostRuleResponse[], required
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` BoostRuleDict, required
            - `filters` FiltersDict
            - `item_ids` string[] — The IDs of the items to be recalled.
            - `boost` number, required — Boost factor for this rule.
          - `rule_type` 'boost', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `content_rules` ContentRuleResponse[], required
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` ContentRuleParameters, required
            - `data` object, required — The data inside the content rule.
          - `rule_type` 'content', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `filters_slot_rules` FiltersSlotRuleResponse[], required
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` FiltersSlotRuleParameters, required
            - `filters` FiltersDict
            - `filter_expression` union
              - …
            - `position_ranges` PositionRange[], required — A list of ranges of positions to place the items.
              - …
            - `labels` object — Can be used to add other miscellaneous properties for the item.
          - `rule_type` 'filters_slot', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
      - RefinedQueryFacetsResponse
        - `id` integer, required
        - `query` string, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `last_updated_internally` string, date-time
        - `last_updated_externally` string, date-time
        - `last_reviewed_at` string, date-time
        - `last_reviewed_by` string
        - `next_review_at` string, date-time
        - `allow_automatic_rules` boolean, required
        - `slot_rules` SlotFacetRuleResponse[], required
          - `target` 'facet_group' | 'facet_option', required
          - `facet_group_name` string
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` SlotFacetRuleParameters, required
            - `name` string, required — The name of the facet to place in position.
            - `position` integer, required — The position of facet to place in.
          - `rule_type` 'slot', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
        - `blacklist_rules` BlacklistFacetRuleResponse[], required
          - `target` 'facet_group' | 'facet_option', required
          - `facet_group_name` string
          - `id` integer, required — The ID of the rule, must be unique.
          - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
          - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
          - `active` boolean — Indicates whether this rule is active or not.
          - `start_time` string, date-time — Date and time when the rule should be enabled.
          - `end_time` string, date-time — Date and time when the rule should be disabled.
          - `campaign_id` integer
          - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
          - `rule` BlacklistFacetRuleParameters, required
            - `name` string, required — The name of the facet to block.
          - `rule_type` 'blacklist', required
          - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
          - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
  - `total_count` integer, required

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