{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/algolia/main/json-schema/algolia-params-schema.json",
  "title": "Run composition parameters as object",
  "x-generated": "2026-09-23",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/algolia-composition-api-openapi.yml#/components/schemas/params",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "analytics": {
      "$ref": "#/$defs/analytics"
    },
    "analyticsTags": {
      "$ref": "#/$defs/analyticsTags"
    },
    "aroundLatLng": {
      "$ref": "#/$defs/aroundLatLng"
    },
    "aroundLatLngViaIP": {
      "$ref": "#/$defs/aroundLatLngViaIP"
    },
    "aroundRadius": {
      "$ref": "#/$defs/aroundRadius"
    },
    "aroundPrecision": {
      "$ref": "#/$defs/aroundPrecision"
    },
    "clickAnalytics": {
      "$ref": "#/$defs/clickAnalytics"
    },
    "enableABTest": {
      "$ref": "#/$defs/enableABTest"
    },
    "enablePersonalization": {
      "$ref": "#/$defs/enablePersonalization"
    },
    "enableReRanking": {
      "$ref": "#/$defs/enableReRanking"
    },
    "enableRules": {
      "$ref": "#/$defs/enableRules"
    },
    "facetFilters": {
      "$ref": "#/$defs/facetFilters"
    },
    "facets": {
      "$ref": "#/$defs/facets"
    },
    "filters": {
      "$ref": "#/$defs/filters"
    },
    "getRankingInfo": {
      "$ref": "#/$defs/getRankingInfo"
    },
    "hitsPerPage": {
      "$ref": "#/$defs/hitsPerPage"
    },
    "injectedItems": {
      "$ref": "#/$defs/injectedItems"
    },
    "insideBoundingBox": {
      "$ref": "#/$defs/insideBoundingBox"
    },
    "insidePolygon": {
      "$ref": "#/$defs/insidePolygon"
    },
    "minimumAroundRadius": {
      "$ref": "#/$defs/minimumAroundRadius"
    },
    "naturalLanguages": {
      "$ref": "#/$defs/naturalLanguages"
    },
    "numericFilters": {
      "$ref": "#/$defs/numericFilters"
    },
    "optionalFilters": {
      "$ref": "#/$defs/optionalFilters"
    },
    "page": {
      "$ref": "#/$defs/page"
    },
    "query": {
      "$ref": "#/$defs/query"
    },
    "queryLanguages": {
      "$ref": "#/$defs/queryLanguages"
    },
    "relevancyStrictness": {
      "$ref": "#/$defs/relevancyStrictness"
    },
    "ruleContexts": {
      "$ref": "#/$defs/ruleContexts"
    },
    "sortBy": {
      "$ref": "#/$defs/sortBy"
    },
    "userToken": {
      "$ref": "#/$defs/userToken"
    }
  },
  "$defs": {
    "analytics": {
      "type": "boolean",
      "description": "Whether this search will be included in Analytics.",
      "default": true,
      "x-categories": [
        "Analytics"
      ]
    },
    "analyticsTags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments).",
      "default": []
    },
    "aroundLatLng": {
      "type": "string",
      "description": "Coordinates for the center of a circle, expressed as a comma-separated string of latitude and longitude.\n\nOnly records included within a circle around this central location are included in the results.\nThe radius of the circle is determined by the `aroundRadius` and `minimumAroundRadius` settings.\nThis parameter is ignored if you also specify `insidePolygon` or `insideBoundingBox`.\n",
      "default": "",
      "x-categories": [
        "Geo-Search"
      ]
    },
    "aroundLatLngViaIP": {
      "type": "boolean",
      "description": "Whether to obtain the coordinates from the request's IP address.",
      "default": false,
      "x-categories": [
        "Geo-Search"
      ]
    },
    "aroundPrecision": {
      "description": "Precision of a coordinate-based search in meters to group results with similar distances.\n\nThe Geo ranking criterion considers all matches within the same range of distances to be equal.\n",
      "oneOf": [
        {
          "type": "integer",
          "default": 10,
          "description": "Distance in meters to group results by similar distances.\n\nFor example, if you set `aroundPrecision` to 100, records wihin 100 meters to the central coordinate are considered to have the same distance,\nas are records between 100 and 199 meters.\n"
        },
        {
          "$ref": "#/$defs/aroundPrecisionFromValue"
        }
      ],
      "x-categories": [
        "Geo-Search"
      ]
    },
    "aroundPrecisionFromValue": {
      "title": "range objects",
      "type": "array",
      "items": {
        "title": "range",
        "type": "object",
        "description": "Range object with lower and upper values in meters to define custom ranges.",
        "properties": {
          "from": {
            "type": "integer",
            "description": "Lower boundary of a range in meters. The Geo ranking criterion considers all records within the range to be equal."
          },
          "value": {
            "type": "integer",
            "description": "Upper boundary of a range in meters. The Geo ranking criterion considers all records within the range to be equal."
          }
        }
      }
    },
    "aroundRadius": {
      "description": "Maximum radius for a search around a central location.\n\nThis parameter works in combination with the `aroundLatLng` and `aroundLatLngViaIP` parameters.\nBy default, the search radius is determined automatically from the density of hits around the central location.\nThe search radius is small if there are many hits close to the central coordinates.\n",
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1,
          "description": "Maximum search radius around a central location in meters."
        },
        {
          "$ref": "#/$defs/aroundRadiusAll"
        }
      ],
      "x-categories": [
        "Geo-Search"
      ]
    },
    "aroundRadiusAll": {
      "title": "all",
      "type": "string",
      "description": "Return all records with a valid `_geoloc` attribute. Don't filter by distance.",
      "enum": [
        "all"
      ]
    },
    "clickAnalytics": {
      "type": "boolean",
      "description": "Whether to include a `queryID` attribute in the response\nThe query ID is a unique identifier for a search query and is required for tracking [click and conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started).\n",
      "default": false,
      "x-categories": [
        "Analytics"
      ]
    },
    "enableABTest": {
      "type": "boolean",
      "description": "Whether to enable index level A/B testing for this run request.\nIf the composition mixes multiple indices, the A/B test is ignored.\n",
      "default": true,
      "x-categories": [
        "Advanced"
      ]
    },
    "enablePersonalization": {
      "type": "boolean",
      "description": "Whether to enable Personalization.",
      "default": false,
      "x-categories": [
        "Personalization"
      ]
    },
    "enableReRanking": {
      "type": "boolean",
      "description": "Whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking)\nThis setting only has an effect if you activated Dynamic Re-Ranking for this index in the Algolia dashboard.\n",
      "default": true,
      "x-categories": [
        "Filtering"
      ]
    },
    "enableRules": {
      "type": "boolean",
      "description": "Whether to enable composition rules.",
      "default": true,
      "x-categories": [
        "Composition Rules"
      ]
    },
    "externalInjectedItem": {
      "type": "object",
      "description": "Contains a list of objects to inject from an external source.\n",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "title": "externalInjection",
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "objectID": {
                "type": "string",
                "description": "An objectID injected from an external source and also present in the targeted index."
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true,
                "description": "User-defined key-values that will be added to the injected item in the response.\nThis is identical to Hits metadata defined in Composition or Composition Rule,\nwith the benefit of being set at runtime.\n"
              }
            },
            "required": [
              "objectID"
            ]
          }
        }
      },
      "required": [
        "items"
      ]
    },
    "facetFilters": {
      "description": "Filter the search by facet values, so that only records with the same facet values are retrieved.\n\n**Prefer using the `filters` parameter, which supports all filter types and combinations with boolean operators.**\n\n- `[filter1, filter2]` is interpreted as `filter1 AND filter2`.\n- `[[filter1, filter2], filter3]` is interpreted as `filter1 OR filter2 AND filter3`.\n- `facet:-value` is interpreted as `NOT facet:value`.\n\nWhile it's best to avoid attributes that start with a `-`, you can still filter them by escaping with a backslash:\n`facet:\\-value`.\n",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/facetFilters"
          }
        },
        {
          "type": "string"
        }
      ],
      "x-categories": [
        "Filtering"
      ]
    },
    "facets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Facets for which to retrieve facet values that match the search criteria and the number of matching facet values\nTo retrieve all facets, use the wildcard character `*`.\nTo retrieve disjunctive facets lists, annotate any facets with the `disjunctive` modifier.\nFor more information, see [facets](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#contextual-facet-values-and-counts) and [disjunctive faceting for Smart Groups](https://www.algolia.com/doc/guides/managing-results/compositions/search-based-groups#facets-including-disjunctive-faceting).\n",
      "default": [],
      "x-categories": [
        "Faceting"
      ]
    },
    "filters": {
      "type": "string",
      "description": "Filter expression to only include items that match the filter criteria in the response.\n\nYou can use these filter expressions:\n\n- **Numeric filters.** `<facet> <op> <number>`, where `<op>` is one of `<`, `<=`, `=`, `!=`, `>`, `>=`.\n- **Ranges.** `<facet>:<lower> TO <upper>`, where `<lower>` and `<upper>` are the lower and upper limits of the range (inclusive).\n- **Facet filters.** `<facet>:<value>`, where `<facet>` is a facet attribute (case-sensitive) and `<value>` a facet value.\n- **Tag filters.** `_tags:<value>` or just `<value>` (case-sensitive).\n- **Boolean filters.** `<facet>: true | false`.\n\nYou can combine filters with `AND`, `OR`, and `NOT` operators with the following restrictions:\n\n- You can only combine filters of the same type with `OR`.\n  **Not supported:** `facet:value OR num > 3`.\n- You can't use `NOT` with combinations of filters.\n  **Not supported:** `NOT(facet:value OR facet:value)`\n- You can't combine conjunctions (`AND`) with `OR`.\n  **Not supported:** `facet:value OR (facet:value AND facet:value)`\n\nUse quotes if the facet attribute name or facet value contains spaces, keywords (`OR`, `AND`, `NOT`), or quotes.\nIf a facet attribute is an array, the filter matches if it matches at least one element of the array.\n\nFor more information, see [Filters](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering).\n",
      "x-categories": [
        "Filtering"
      ]
    },
    "getRankingInfo": {
      "type": "boolean",
      "description": "Whether the run response should include detailed ranking information.",
      "default": false,
      "x-categories": [
        "Advanced"
      ]
    },
    "hitsPerPage": {
      "type": "integer",
      "description": "Number of hits per page.",
      "default": 20,
      "minimum": 1,
      "maximum": 1000,
      "x-categories": [
        "Pagination"
      ]
    },
    "injectedItems": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/externalInjectedItem"
      },
      "description": "An object containing keys corresponding to the `key`s from an injection's `injectedItems` and values containing a list of hits to inject.\n",
      "default": {},
      "x-categories": [
        "Retail Media Network"
      ]
    },
    "insideBoundingBox": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/insideBoundingBoxArray"
        }
      ]
    },
    "insideBoundingBoxArray": {
      "type": "array",
      "items": {
        "type": "array",
        "minItems": 4,
        "maxItems": 4,
        "items": {
          "type": "number",
          "format": "double"
        }
      },
      "description": "Coordinates for a rectangular area in which to search.\n\nEach bounding box is defined by the two opposite points of its diagonal, and expressed as latitude and longitude pair:\n`[p1 lat, p1 long, p2 lat, p2 long]`.\nProvide multiple bounding boxes as nested arrays.\nFor more information, see [rectangular area](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).\n",
      "x-categories": [
        "Geo-Search"
      ]
    },
    "insidePolygon": {
      "type": "array",
      "items": {
        "type": "array",
        "minItems": 6,
        "maxItems": 20000,
        "items": {
          "type": "number",
          "format": "double"
        }
      },
      "description": "Coordinates of a polygon in which to search.\n\nPolygons are defined by 3 to 10,000 points. Each point is represented by its latitude and longitude.\nProvide multiple polygons as nested arrays.\nFor more information, see [filtering inside polygons](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).\nThis parameter is ignored if you also specify `insideBoundingBox`.\n",
      "x-categories": [
        "Geo-Search"
      ]
    },
    "minimumAroundRadius": {
      "type": "integer",
      "description": "Minimum radius (in meters) for a search around a location when `aroundRadius` isn't set.",
      "minimum": 1,
      "x-categories": [
        "Geo-Search"
      ]
    },
    "naturalLanguages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/supportedLanguage"
      },
      "description": "ISO language codes that adjust settings that are useful for processing natural language queries (as opposed to keyword searches)\n- Sets `removeStopWords` and `ignorePlurals` to the list of provided languages.\n- Sets `removeWordsIfNoResults` to `allOptional`.\n- Adds a `natural_language` attribute to `ruleContexts` and `analyticsTags`.\n",
      "default": [],
      "x-categories": [
        "Languages"
      ]
    },
    "numericFilters": {
      "description": "Filter by numeric facets.\n\n**Prefer using the `filters` parameter, which supports all filter types and combinations with boolean operators.**\n\nYou can use numeric comparison operators: `<`, `<=`, `=`, `!=`, `>`, `>=`.\nComparisons are precise up to 3 decimals.\nYou can also provide ranges: `facet:<lower> TO <upper>`. The range includes the lower and upper boundaries.\nThe same combination rules apply as for `facetFilters`.\n",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/numericFilters"
          }
        },
        {
          "type": "string"
        }
      ],
      "x-categories": [
        "Filtering"
      ]
    },
    "optionalFilters": {
      "description": "Filters to promote or demote records in the search results.\n\nOptional filters work like facet filters, but they don't exclude records from the search results.\nRecords that match the optional filter rank before records that don't match.\nIf you're using a negative filter `facet:-value`, matching records rank after records that don't match.\n\n- Optional filters are applied _after_ sort-by attributes.\n- Optional filters are applied _before_ custom ranking attributes (in the default [ranking](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria)).\n- Optional filters don't work with numeric attributes.\n- On virtual replicas, optional filters are applied _after_ the replica's [relevant sort](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/relevant-sort).\n",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/optionalFilters"
          }
        },
        {
          "type": "string"
        }
      ],
      "x-categories": [
        "Filtering"
      ]
    },
    "page": {
      "type": "integer",
      "description": "Page of search results to retrieve.",
      "default": 0,
      "minimum": 0,
      "x-categories": [
        "Pagination"
      ]
    },
    "query": {
      "type": "string",
      "description": "Search query.",
      "default": "",
      "x-categories": [
        "Search"
      ]
    },
    "queryLanguages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/supportedLanguage"
      },
      "description": "Languages for language-specific query processing steps such as plurals, stop-word removal, and word-detection dictionaries.\nThis setting sets a default list of languages used by the `removeStopWords` and `ignorePlurals` settings.\nThis setting also sets a dictionary for word detection in the logogram-based [CJK](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/#normalization-for-logogram-based-languages-cjk) languages.\nTo support this, place the CJK language **first**.\n**Always specify a query language.**\nIf you don't specify an indexing language, the search engine uses all [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages),\nor the languages you specified with the `ignorePlurals` or `removeStopWords` parameters.\nThis can lead to unexpected search results.\nFor more information, see [Language-specific configuration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations).\n",
      "default": [],
      "x-categories": [
        "Languages"
      ]
    },
    "relevancyStrictness": {
      "type": "integer",
      "description": "Relevancy threshold below which less relevant results aren't included in the results\nYou can only set `relevancyStrictness` on [virtual replica indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/#what-are-virtual-replicas).\nUse this setting to strike a balance between the relevance and number of returned results.\n",
      "default": 100,
      "x-categories": [
        "Ranking"
      ]
    },
    "ruleContexts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Assigns a rule context to the run query\n[Rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#whats-a-context) are strings that you can use to trigger matching rules.\n",
      "default": [],
      "x-categories": [
        "Composition Rules"
      ]
    },
    "sortBy": {
      "type": "string",
      "description": "Indicates which sorting strategy to apply for the request.\nThe value must match one of the labels defined in the \"sortingStrategy\" mapping. For example, \"Price (asc)\", see Upsert Composition.\nAt runtime, this label is used to look up the corresponding index or replica configured in \"sortingStrategy\", and the query is executed using that index instead of main's.\n\nIn addition to \"sortingStrategy\", this parameter is also used to apply a matching Composition Rule that contains a condition defined to trigger on \"sortBy\", see Composition Rules.\n\nIf no value is provided or an invalid value, no sorting strategy is applied.\n",
      "default": ""
    },
    "supportedLanguage": {
      "type": "string",
      "description": "ISO code for a supported language.",
      "enum": [
        "af",
        "ar",
        "az",
        "bg",
        "bn",
        "ca",
        "cs",
        "cy",
        "da",
        "de",
        "el",
        "en",
        "eo",
        "es",
        "et",
        "eu",
        "fa",
        "fi",
        "fo",
        "fr",
        "ga",
        "gl",
        "he",
        "hi",
        "hu",
        "hy",
        "id",
        "is",
        "it",
        "ja",
        "ka",
        "kk",
        "ko",
        "ku",
        "ky",
        "lt",
        "lv",
        "mi",
        "mn",
        "mr",
        "ms",
        "mt",
        "nb",
        "nl",
        "no",
        "ns",
        "pl",
        "ps",
        "pt",
        "pt-br",
        "qu",
        "ro",
        "ru",
        "sk",
        "sq",
        "sv",
        "sw",
        "ta",
        "te",
        "th",
        "tl",
        "tn",
        "tr",
        "tt",
        "uk",
        "ur",
        "uz",
        "zh"
      ]
    },
    "userToken": {
      "type": "string",
      "description": "Unique pseudonymous or anonymous user identifier.\n\nThis helps with analytics and click and conversion events.\nFor more information, see [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken).\n",
      "x-categories": [
        "Personalization"
      ]
    }
  }
}