---
title: "Retrieve campaigns"
method: GET
path: "/v1/campaigns"
tags: ["Searchandising campaigns"]
---

# Retrieve campaigns

`GET /v1/campaigns`

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

Retrieve campaigns.

## 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` union — The ID(s) of campaigns to filter by.
  - integer
  - integer[]
- `refined_filters` object — A list of refined filters.
- `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`.
- `refined_recommendation_contexts` RefinedRecommendationContext
  - `pod_id` string[] — A list of pod IDs.
  - `condition_type` RefinedStrategyType[] — A list of condition types. Can be "item", "attribute", or "expression"
- `refined_queries` string[] — A list of refined queries.

## Response `200`

OK

- CampaignListGetResponse
  - `campaigns` Campaign[], required — A list of campaigns.
    - `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.
    - `start_time` string, date-time — The start time of the campaign.
    - `end_time` string, date-time — The end time of the campaign.
    - `name` string — The name of the campaign.
    - `description` string — The description of the campaign.
    - `refined_queries` RefinedQuery[] — A list of refined queries.
      - `query` string, required — A refined query string
    - `refined_filters` RefinedFilter[] — A list of refined filters.
      - `filter_name` string, required — The name of the refined filter.
      - `filter_value` string, required — The value of the refined filter.
    - `refined_recommendation_contexts` RecommendationContext[] — A list of refined recommendation contexts.
      - `pod_id` string, required — The ID of the pod.
      - `condition` union, required — Condition of the context
        - RecommendationContextItemCondition
          - `type` 'item', required
          - `item_id` string — The ID of the item.
        - RecommendationContextAttributeCondition
          - `type` 'attribute', required
          - `filter_name` string — The name of the refined filter.
          - `filter_value` string — The value of the refined filter.
        - RecommendationContextExpressionCondition
          - `type` 'expression', required
          - `expression` object, required — Object where keys are filter names, values are lists of filter values.
    - `boost_rules` BoostRuleResponse[] — A list of boost rules.
      - `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.
    - `blacklist_rules` BlacklistRuleResponse[] — A list of blacklist rules.
      - `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.
    - `slot_rules` SlotRuleResponse[] — A list of slot rules.
      - `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.
    - `content_rules` ContentRuleResponse[] — A list of content rules.
      - `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[] — A list of filters slot rules.
      - `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
          - object
          - string, json
        - `position_ranges` PositionRange[], required — A list of ranges of positions to place the items.
          - `start` integer, required — The start position of the slot.
          - `end` integer, required — The end position of the slot.
        - `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.
    - `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.
    - `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
          - object
          - string, json
      - `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.
    - `metadata_json` CampaignMetadata
      - `goal` string — The goal of the campaign.
      - `goal_description` string — A description of the campaign goal.
    - `id` integer, required — The ID of the campaign.
    - `created_at` string, date-time, required — The creation time of the campaign.
    - `updated_at` string, date-time, required — The last updated time of the campaign.
  - `total_count` integer, required — The total count of campaigns.

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