# Smart Search
Smart search endpoints
## Get smart search results
> Returns personalized search results for sport events and casino games.\
> \
> {% hint style="info" %}\
> \
> \## For sports\
> \
> \
> The endpoint supports searches based on both participant/country/league\
> similarity and user preferences.The returned results are events that include\
> at least one participant/country/league that has string similarities with\
> the searched token. Using the \`mode\` option, the ranking of these events can\
> be based on the user preferences or on event popularity in addition to the\
> string similarity. We also support events filtering by providing a\
> score threshold.\
> \
> Only events starting between the requested time range will be considered.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## For casino\
> \
> \
> The endpoint supports searches based on game's name, category, studio and\
> vaix tags.The returned results are casino games that include at least one\
> field that has string similarities with the searched token.\
> \
> {% endhint %}\
> \
> \
> Spelling mistakes, whitespace, typos and many more filters\
> are supported by default for sport and casino product.\
> \
> {% hint style="info" %}\
> \
> \## Picking the correct date parameters for sport events\
> \
> \
> Most of the times it is advised to use a tight date range (ex. 1 week).\
> This avoids season bets and also boosts events that are starting the\
> following days where the player may be more interested.\
> \
> {% endhint %}\
> \
> \
> {% hint style="warning" %}\
> \
> \## Search product\
> \
> \
> You must specify in which product(sport/casino) you are searching for.\
> Make sure to fill out the \`product\` query parameter.\
> \
> {% endhint %}\
```json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Smart search endpoints","name":"Smart Search"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"SmartSearch":{"oneOf":[{"additionalProperties":false,"description":"A smart search sport response object","properties":{"events":{"description":"A list of sport event objects","type":"array","items":{"additionalProperties":false,"description":"A sport's event object","properties":{"selection_id":{"description":"The market selection id","type":"string"},"quote":{"description":"The selection's quote","type":"number"},"inserted_at":{"description":"date of the event inserted","type":"string","format":"date-time","nullable":true},"uof_external_id":{"description":"The external market id","type":"string","nullable":true},"period":{"description":"The selection's period","type":"string","nullable":true},"market_type":{"description":"The market's type","type":"string","nullable":true},"period_id":{"description":"The `period`'s id","type":"number","nullable":true},"markets":{"description":"The markets of the event","type":"array","items":{"additionalProperties":false,"description":"A smart search sport market response object","properties":{"event_id":{"description":"The event identifier","type":"string"},"id":{"description":"The market identifier","type":"string"},"market_id":{"description":"The market identifier","type":"number"},"market_type":{"description":"The market type","type":"string"},"market_type_id":{"description":"The market type identifier","type":"number"},"name":{"description":"The market name","type":"string"},"outcome":{"description":"The market outcome","type":"string"},"quote":{"description":"The market quote","type":"number"},"score":{"description":"Search score, the highest the value the more relevant the result is.","type":"number"},"status":{"description":"The market status","type":"string"}},"type":"object"}},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"league_id":{"description":"The id of the event's league","type":"string","nullable":true},"status":{"description":"The status of the event, e.g. `live`","type":"string"},"opened":{"description":"date of the event opened","type":"string","format":"date-time","nullable":true},"updated_at":{"description":"date of the event inserted","type":"string","format":"date-time","nullable":true},"quote_group":{"description":"The group the quote belongs to","type":"string"},"outcome":{"description":"The selection's outcome","type":"string","nullable":true},"ended":{"description":"date of the event end","type":"string","format":"date-time","nullable":true},"outcome_id":{"description":"The `outcome`'s id","type":"number","nullable":true},"participant_ids":{"description":"The id of the event participants","type":"array","items":{"type":"string"},"nullable":true},"brand":{"description":"The operator's brand","type":"string"},"market_id":{"description":"The `market`'s id","type":"number","nullable":true},"bet_offer_id":{"description":"The event specific market id","type":"string","nullable":true},"country":{"description":"The country the event takes place at","type":"string","nullable":true},"league":{"description":"The league associated with the current event","type":"string","nullable":true},"market_type_id":{"description":"The `market_type`'s id","type":"number","nullable":true},"event_type":{"description":"The type of the event, e.g. `outright","type":"string","nullable":true},"sport":{"description":"The sport of the event, e.g. `soccer`","type":"string","nullable":true},"country_id":{"description":"The id of the country the event takes place at","type":"string","nullable":true},"event_id":{"description":"The event identifier","type":"string"},"sport_id":{"description":"The id of the event's sport","type":"string","nullable":true},"market":{"description":"The market's name","type":"string","nullable":true},"participants":{"description":"The participants of the event","type":"array","items":{"type":"string"},"nullable":true},"begin":{"description":"The starting time of the event in UTC","type":"string","format":"date-time"},"score":{"description":"Search score, the highest the value the more relevant the result is.","type":"number"}},"type":"object"}}},"type":"object"},{"additionalProperties":false,"description":"A smart search casino response object","properties":{"games":{"description":"A list of casino game objects","type":"array","items":{"additionalProperties":false,"description":"A casino game object","properties":{"game_id":{"description":"The identifier of the casino game","type":"string"},"game_image_url":{"description":"The casino game image URL","type":"string","nullable":true},"game_name":{"description":"The name of the casino game","type":"string"},"game_studio":{"description":"The studio of the casino game","type":"string"},"score":{"description":"Search score, the highest the value the more relevant the result is.","type":"number"},"vaix_tags":{"description":"The vaix tags for the casino game","type":"string"}},"type":"object"}}},"type":"object"}]},"Error":{"description":"The generic API's error response","type":"object","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"additionalProperties":false},"Errors":{"description":"The generic API's errors response","type":"object","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"additionalProperties":false},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/search":{"get":{"operationId":"get_smart_search_results","summary":"Get smart search results","description":"Returns personalized search results for sport events and casino games.\n\n{% hint style=\"info\" %}\n\n## For sports\n\n\nThe endpoint supports searches based on both participant/country/league\nsimilarity and user preferences.The returned results are events that include\nat least one participant/country/league that has string similarities with\nthe searched token. Using the `mode` option, the ranking of these events can\nbe based on the user preferences or on event popularity in addition to the\nstring similarity. We also support events filtering by providing a\nscore threshold.\n\nOnly events starting between the requested time range will be considered.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## For casino\n\n\nThe endpoint supports searches based on game's name, category, studio and\nvaix tags.The returned results are casino games that include at least one\nfield that has string similarities with the searched token.\n\n{% endhint %}\n\n\nSpelling mistakes, whitespace, typos and many more filters\nare supported by default for sport and casino product.\n\n{% hint style=\"info\" %}\n\n## Picking the correct date parameters for sport events\n\n\nMost of the times it is advised to use a tight date range (ex. 1 week).\nThis avoids season bets and also boosts events that are starting the\nfollowing days where the player may be more interested.\n\n{% endhint %}\n\n\n{% hint style=\"warning\" %}\n\n## Search product\n\n\nYou must specify in which product(sport/casino) you are searching for.\nMake sure to fill out the `product` query parameter.\n\n{% endhint %}\n\n","parameters":[{"name":"x-vaix-client-id","in":"header","description":"Custom client header, the value should be the name of the group the user belongs to","required":true,"schema":{"type":"string"}},{"name":"x-vaix-authentication-method","in":"header","description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","required":false,"schema":{"type":"string"}},{"name":"token","in":"query","description":"The search pattern.","required":true,"schema":{"type":"string"}},{"name":"product","in":"query","description":"The product to search for.","required":true,"schema":{"type":"string","enum":["sport","casino"]}},{"name":"count","in":"query","description":"Number of events to return.\n","required":false,"schema":{"type":"integer","default":50,"minimum":1}},{"name":"brand","in":"query","description":"The brand of the operator.","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"from_offset","in":"query","description":"How many minutes/hours/days to shift `from`. Use a negative value for a\nbackwards shift, or a positive value for a forwards shift.\nThe value must be in range [`-7d` - `7d`].\n","required":false,"schema":{"type":"string","default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$"}},{"name":"score_threshold","in":"query","description":"Filters events based on their calculated score. If not set defaults to\n0.5. The value must be in range [0.0-1.0].\n","required":false,"schema":{"type":"number","maximum":1,"minimum":0}},{"name":"to_offset","in":"query","description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to one week (7 days).\nThe value must be in range [`0d` - `14`].\n","required":false,"schema":{"type":"string","default":"7d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$"}},{"name":"mode","in":"query","description":"Decides whether the smart search results will be returned as is, mixed by\npopular events, or mixed by user recommendations (default). When mode is\n`recommended`, `user` must also be provided, otherwise the results will\nfall back to `popular` mode.\n","required":false,"schema":{"type":"string","default":"recommended","enum":["recommended","popular","unmixed"]}},{"name":"filters","in":"query","description":"A mix of sports and casino filters. This parameter is useful to specify specific\nfilters on the data you want to return. The appropriate filters for the product\nin use should be applied. Sports and Casino filters cannot be mixed, otherwise\nan error response will be returned.\n","required":false,"schema":{"type":"string","enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids","game_id","game_studio","category","vaix_tags","tags","channels","has_megaways","is_live","has_bonus","has_buy","has_jackpot","has_sticky","has_avalanche","has_fixed","has_free_spin","has_wilds","has_gamble","has_respin","has_scatter","has_symbols_collection","has_symbols_mega","has_symbols_expanding","has_symbols_mystery","has_multiplier","has_wilds_random","has_wilds_walking","enabled","has_megaways","game_country","is_live","has_bonus","has_buy","has_jackpot","has_sticky","has_avalanche","has_fixed","has_free_spin","has_wilds","has_gamble","has_respin","has_scatter","has_symbols_collection","has_symbols_mega","has_symbols_expanding","has_symbols_mystery","has_multiplier","has_wilds_random","has_wilds_walking","live"]}},{"name":"user","in":"query","description":"The user to get recommendations for.","required":false,"schema":{"type":"string","default":"0"}},{"name":"language","in":"query","description":"The language to perform searches for. Depends on the available translations\nand will be ignored if the provided language is invalid.\n","required":false,"schema":{"type":"string"}},{"name":"operator","in":"query","description":"The operator to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored.\n","required":false,"schema":{"type":"string"}},{"name":"bookmaker_id","in":"query","description":"The bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`sub_bookmaker_id` parameter.\n","required":false,"schema":{"type":"integer"}},{"name":"sub_bookmaker_id","in":"query","description":"The sub-bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`bookmaker_id` parameter.\n","required":false,"schema":{"type":"integer"}},{"name":"fields","in":"query","description":"Optional selection of the object fields to retrieve. It expects a comma\nseparated list of strings, as described in the field selection section,\ne.g. `markets,event_id`.\n","required":false,"schema":{"type":"string","default":["markets","event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","score","game_id","game_name","game_studio","category","vaix_tags","tags","channels","game_image_url","rec_score","has_avalanche","has_bonus","has_buy","has_jackpot","is_live","has_megaways","has_sticky","has_fixed","has_free_spin","has_wilds","has_gamble","has_respin","has_scatter","has_symbols_collection","has_symbols_mega","has_symbols_expanding","has_symbols_mystery","has_multiplier","has_wilds_random","has_wilds_walking"],"enum":["markets","event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","score","game_id","game_name","game_studio","category","vaix_tags","tags","channels","game_image_url","rec_score","has_avalanche","has_bonus","has_buy","has_jackpot","is_live","has_megaways","has_sticky","has_fixed","has_free_spin","has_wilds","has_gamble","has_respin","has_scatter","has_symbols_collection","has_symbols_mega","has_symbols_expanding","has_symbols_mystery","has_multiplier","has_wilds_random","has_wilds_walking"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"description":"API response","type":"object","properties":{"data":{"$ref":"#/components/schemas/SmartSearch"},"status":{"description":"The status of the request","type":"string","enum":["success","error"]}},"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}}},"425":{"description":"Too Early","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Smart Search"]}}}}
```
## Get smart search requests
> Returns the smart search requests made by a user.\
> \
> This endpoint helps you retrieve the search queries a user has performed,\
> optionally applying filters and sorting. Supports filtering by uniqueness and without uniqueness.\
> \
> \### Example\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> \--url "
> \`\`\`\
> \
> The above will return the 5 most recent search requests\
> for user user123 sorted by most recent first.
````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Smart search endpoints","name":"Smart Search"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"Searches":{"description":"A search request object","type":"object","properties":{"location":{"description":"The location of the search request","type":"string"},"raw_search_token":{"description":"The raw search token","type":"string"},"timestamp":{"description":"The timestamp of the search request","type":"string","format":"date-time"},"user_id":{"description":"The user identifier","type":"string"}},"additionalProperties":false},"Error":{"description":"The generic API's error response","type":"object","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"additionalProperties":false},"Errors":{"description":"The generic API's errors response","type":"object","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"additionalProperties":false},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/search/searches":{"get":{"operationId":"get_smart_search_searches","summary":"Get smart search requests","description":"Returns the smart search requests made by a user.\n\nThis endpoint helps you retrieve the search queries a user has performed,\noptionally applying filters and sorting. Supports filtering by uniqueness and without uniqueness.\n\n### Example\n\n```bash\n$ curl --request GET \\\n --url \"http://api.vaix.ai/api/search/searches?user=user123&order_by=-timestamp&count=5\"\n```\n\nThe above will return the 5 most recent search requests\nfor user user123 sorted by most recent first.\n","parameters":[{"name":"x-vaix-client-id","in":"header","description":"Custom client header, the value should be the name of the group the user belongs to","required":true,"schema":{"type":"string"}},{"name":"x-vaix-authentication-method","in":"header","description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","required":false,"schema":{"type":"string"}},{"name":"user","in":"query","description":"The user to get searches for.","required":true,"schema":{"type":"string"}},{"name":"unique","in":"query","description":"If set (default), only unique search terms will be returned.\nOtherwise all matching searches will be returned.\n","required":false,"schema":{"type":"boolean","default":true}},{"name":"filters","in":"query","description":"Optional filtering of the searches to retrieve.\nIt expects a string adhering to the filtering format,\nas described in the filtering section.\n\nYou can also use `days_since_search` (e.g. `days_since_search:eq:30`)\ninstead of explicit timestamp ranges.\n","required":false,"schema":{"type":"string","enum":["timestamp","location","days_since_search"]}},{"name":"order_by","in":"query","description":"The columns to sort the results by. It expects a string adhering to\nthe ordering format, as described in the ordering section, e.g.\n`+timestamp,-location`.\n","required":false,"schema":{"type":"string","default":"-timestamp","enum":["timestamp","location"]}},{"name":"count","in":"query","description":"Maximum number of results.","required":false,"schema":{"type":"integer","default":20,"maximum":100,"minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"description":"API response","type":"object","properties":{"data":{"description":"Array of objects","type":"array","items":{"$ref":"#/components/schemas/Searches"}},"status":{"description":"The status of the request","type":"string","enum":["success","error"]}},"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}}},"425":{"description":"Too Early","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Smart Search"]}}}}
````
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sportradar.com/personalization/api-reference/smart-search.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.