# Selections

Selections related endpoints

## Get recommended selections

> Returns recommended selections for the given user.\
> \
> The top \`count\` recommended events for the given user are fetched.\
> For each of these events, the top \`selection\_count\` selections are returned.\
> \
> {% hint style="info" %}\
> \
> \## Recommended selections per event\
> \
> \
> The recommended selections returned per event are also personalized\
> based on the user's preferences.\
> \
> Notice that in the case of multiple selections per event, each selection\
> will be of different market type.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Getting recommended selections\
> \
> \
> In this example we get \`3\` recommended events for the user with id \`1\`.\
> For each of these events, we request \`2\` selections.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/selections/recommended?user=1\\&count=3%3Aeq%3Aselection\\_count=2'\\>
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Selections related endpoints","name":"Selections"}],"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":{"RecommendedSelection":{"additionalProperties":false,"description":"A recommended selection object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_confidence":{"description":"The highest confidence across the recommendations of the same country.\n","type":"number"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_confidence":{"description":"The highest confidence across the recommendations of the same league.\n","type":"number"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"selections":{"description":"The event's recommended selections","items":{"type":"object"},"type":"array"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_confidence":{"description":"The highest confidence across the recommendations of the same sport.\n","type":"number"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"}},"type":"object"},"Error":{"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"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"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/sports/selections/recommended":{"get":{"description":"Returns recommended selections for the given user.\n\nThe top `count` recommended events for the given user are fetched.\nFor each of these events, the top `selection_count` selections are returned.\n\n{% hint style=\"info\" %}\n\n## Recommended selections per event\n\n\nThe recommended selections returned per event are also personalized\nbased on the user's preferences.\n\nNotice that in the case of multiple selections per event, each selection\nwill be of different market type.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Getting recommended selections\n\n\nIn this example we get `3` recommended events for the user with id `1`.\nFor each of these events, we request `2` selections.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/selections/recommended?user=1&count=3%3Aeq%3Aselection_count=2'\n```\n\n{% endhint %}\n\n","operationId":"get_recommended_selections","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"The user id.","in":"query","name":"user","required":true,"schema":{"type":"string"}},{"description":"Number of selections to return for each event.\n","in":"query","name":"selection_count","required":false,"schema":{"default":1,"minimum":1,"type":"integer"}},{"description":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering on the events and markets to consider for the returned selections.\nIt expects a string adhering to the filtering format, as described in the filtering section,\ne.g. `sport:eq:Soccer;market:eq:1X2`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","participants","participant_ids","status","booking_status","event_type","market","market_id","market_type","market_type_id","outcome","outcome_id","market_status","market_group_status","trade_status","trade_market_status","quote","boosted_odds","user_country","user_state"],"type":"string"}},{"description":"The minimum event's starting datetime.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to 2 days.\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"The event ids to get selections for. If not set, the most recommended events for the user will be automatically picked.\n","in":"query","name":"event_ids","required":false,"schema":{"type":"string"}},{"description":"Excludes the top `n` popular selections from the results.\n","in":"query","name":"exclude_n_popular","required":false,"schema":{"default":0,"type":"integer"}},{"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. `event_id,event_type`.\n","in":"query","name":"fields","required":false,"schema":{"default":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count","confidence"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count","confidence"],"type":"string"}},{"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","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"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","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"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","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"Applies a limit to a group of items. For more information, head to\n`Limiting -> Group Limiting` section of the docs.\n`country:5,country_id:2`.\n","in":"query","name":"group_limit","required":false,"schema":{"enum":["country","country_id","league","league_id","sport","sport_id","event_type"],"type":"string"}},{"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`+event_confidence,-league_confidence`.\n","in":"query","name":"order_by","required":false,"schema":{"enum":["event_confidence","league_confidence","sport_confidence","country_confidence","begin","event_id"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Comma separated list of keywords. If given, this input will be used\nas user demographics data for the recommendations, e.g `country:gr,city:ath`.\n","in":"query","name":"raw","required":false,"schema":{"enum":["age_group","city","country"],"type":"string"}},{"description":"Optional re ordering of the results based on one or more metrics.\nExpected format is a comma separated list of keywords where each value\nshould be a float in the range [0,1]. e.g. `popular:0.3,trending:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["popular","trending"],"type":"string"}},{"description":"Number of items to use when reordering items with `reorder_by` parameter. This\nparameter is meaningful only when `reorder_by` is also set. If not set, then `count`\nwill be used as population.\n","in":"query","name":"population","required":false,"schema":{"minimum":1,"type":"integer"}},{"description":"Limit results to a specified number of diverse values for a field.\nFor example, `sport:3,sport_id:2` will return items from at most\nthe specified number of different values for each field.\n","in":"query","name":"diversity_limit","required":false,"schema":{"description":"A string in the format 'field:value', where 'field' is a supported field and 'value' is a positive integer. Used for configuration, filtering, or limiting based on field values.","enum":["sport","sport_id","league","league_id","event_id"],"type":"string"}},{"description":"Excludes results based on the most recommended values for a field.\nFor example, `sport_id:1` will exclude all items from\nthe user's most recommended value(s) for that field.\n","in":"query","name":"exclude_top","required":false,"schema":{"description":"A string in the format 'field:value', where 'field' is a supported field and 'value' is a positive integer. Used for configuration, filtering, or limiting based on field values.","enum":["event_id","sport","sport_id","league","league_id","country","country_id"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/RecommendedSelection"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get recommended selections","tags":["Selections"]}}}}
````

## Get popular selections

> Get popular selections for the given time range.\
> \
> Only events starting between the given time range will be considered\
> and the most popular selections across these events will be returned.\
> \
> {% hint style="info" %}\
> \
> \## Flat vs nested response\
> \
> \
> Two options are supported for the response format.\
> \
> \* Flat: The event and selection info are returned merged in a single object.\
> The results are sorted based on popularity\
> \* Nested: The selections are returned grouped by their events. Each event's\
> selections are sorted based on popularity.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Availability of results\
> \
> \
> Notice that if no bets for the available selections have been placed\
> in the given time frame, no results will be returned.\
> \
> {% endhint %}\ <br>

```json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Selections related endpoints","name":"Selections"}],"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":{"PopularSelection":{"oneOf":[{"additionalProperties":false,"description":"A popular selection nested object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"selections":{"description":"The event's popular selections","items":{"type":"object"},"type":"array"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"A popular selection flat object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"bet_offer_id":{"description":"The event specific market id","nullable":true,"type":"string"},"count":{"description":"How many bets are placed on the market","type":"integer"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"market":{"description":"The market's name","nullable":true,"type":"string"},"market_id":{"description":"The `market`'s id","nullable":true,"type":"number"},"market_type":{"description":"The market's type","nullable":true,"type":"string"},"market_type_id":{"description":"The `market_type`'s id","nullable":true,"type":"number"},"outcome":{"description":"The selection's outcome","nullable":true,"type":"string"},"outcome_id":{"description":"The `outcome`'s id","nullable":true,"type":"number"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"period":{"description":"The selection's period","nullable":true,"type":"string"},"period_id":{"description":"The `period`'s id","nullable":true,"type":"number"},"quote":{"description":"The selection's quote","type":"number"},"quote_group":{"description":"The group the quote belongs to","type":"string"},"selection_id":{"description":"The market selection id","type":"string"},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"},"uof_external_id":{"description":"The external market id","nullable":true,"type":"string"}},"type":"object"}]},"Error":{"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"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"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/sports/selections/popular":{"get":{"description":"Get popular selections for the given time range.\n\nOnly events starting between the given time range will be considered\nand the most popular selections across these events will be returned.\n\n{% hint style=\"info\" %}\n\n## Flat vs nested response\n\n\nTwo options are supported for the response format.\n\n* Flat: The event and selection info are returned merged in a single object.\nThe results are sorted based on popularity\n* Nested: The selections are returned grouped by their events. Each event's\nselections are sorted based on popularity.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Availability of results\n\n\nNotice that if no bets for the available selections have been placed\nin the given time frame, no results will be returned.\n\n{% endhint %}\n\n","operationId":"get_popular_selections","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"Number of selections to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"maximum":100,"minimum":1,"type":"integer"}},{"description":"Comma separated list of event ids for which to return selections.\n","in":"query","name":"event_ids","required":false,"schema":{"type":"string"}},{"description":"Optional filtering on the events and markets to consider for the returned selections.\nIt expects a string adhering to the filtering format, as described in the filtering section,\ne.g. `sport:eq:Soccer;market:eq:1X2`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","participants","participant_ids","status","booking_status","event_type","market","market_id","market_type","market_type_id","outcome","outcome_id","market_status","market_group_status","trade_status","trade_market_status","quote","boosted_odds"],"type":"string"}},{"description":"The minimum event's starting datetime.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to 2 days.\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"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. `event_id,event_type`.\n","in":"query","name":"fields","required":false,"schema":{"default":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count"],"type":"string"}},{"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","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"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","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"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","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/PopularSelection"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get popular selections","tags":["Selections"]}}}}
```

## Get trending selections

> Get trending selections for the given time frame.\
> \
> Only events starting between the given time range will be considered\
> and the most trending selections across these events will be returned.\
> \
> {% hint style="info" %}\
> \
> \## Flat vs Nested response\
> \
> \
> Two options are supported for the response format.\
> \
> \* Flat: The event and selection info are returned merged in a single object.\
> The results are sorted based on trending score.\
> \* Nested: The selections are returned group by their events, so if more than\
> one selections correspond to the same event, these will be grouped\
> in the \`selections\` field of the given event object. Each event's\
> selections are sorted based on trending score.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Trending score\
> \
> \
> To calculate trending score for a selection, each bet placed on this selection\
> contributes a value determined by how recently the bet was placed.\
> \
> Recent bets add more value than older ones.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Getting trending selections\
> \
> \
> In this example we get 10 trending selections for events played in China.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/selections/trending?count=10\\&filters=country%3Aeq%3AChina'\\>
> \`\`\`\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Availability of results\
> \
> \
> Notice that if no bets for the available selections have been placed\
> in the given time frame, no results will be returned.\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Selections related endpoints","name":"Selections"}],"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":{"TrendingSelection":{"oneOf":[{"additionalProperties":false,"description":"A trending selection nested object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"selections":{"description":"The event's trending selections","items":{"properties":{"bet_offer_id":{"description":"The event specific market id","nullable":true,"type":"string"},"count":{"description":"How many bets are placed on the market","type":"integer"},"market":{"description":"The market's name","nullable":true,"type":"string"},"market_id":{"description":"The `market`'s id","nullable":true,"type":"number"},"market_type":{"description":"The market's type","nullable":true,"type":"string"},"market_type_id":{"description":"The `market_type`'s id","nullable":true,"type":"number"},"outcome":{"description":"The selection's outcome","nullable":true,"type":"string"},"outcome_id":{"description":"The `outcome`'s id","nullable":true,"type":"number"},"period":{"description":"The selection's period","nullable":true,"type":"string"},"period_id":{"description":"The `period`'s id","nullable":true,"type":"number"},"quote":{"description":"The selection's quote","type":"number"},"quote_group":{"description":"The group the quote belongs to","type":"string"},"selection_id":{"description":"The market selection id","type":"string"},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"uof_external_id":{"description":"The external market id","nullable":true,"type":"string"}},"type":"object"},"type":"array"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"A trending selection flat object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"bet_offer_id":{"description":"The event specific market id","nullable":true,"type":"string"},"count":{"description":"How many bets are placed on the market","type":"integer"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"market":{"description":"The market's name","nullable":true,"type":"string"},"market_id":{"description":"The `market`'s id","nullable":true,"type":"number"},"market_type":{"description":"The market's type","nullable":true,"type":"string"},"market_type_id":{"description":"The `market_type`'s id","nullable":true,"type":"number"},"outcome":{"description":"The selection's outcome","nullable":true,"type":"string"},"outcome_id":{"description":"The `outcome`'s id","nullable":true,"type":"number"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"period":{"description":"The selection's period","nullable":true,"type":"string"},"period_id":{"description":"The `period`'s id","nullable":true,"type":"number"},"quote":{"description":"The selection's quote","type":"number"},"quote_group":{"description":"The group the quote belongs to","type":"string"},"score":{"description":"Trending score, the highest the score the more trending the item","type":"number"},"selection_id":{"description":"The market selection id","type":"string"},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"},"uof_external_id":{"description":"The external market id","nullable":true,"type":"string"}},"type":"object"}]},"Error":{"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"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"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/sports/selections/trending":{"get":{"description":"Get trending selections for the given time frame.\n\nOnly events starting between the given time range will be considered\nand the most trending selections across these events will be returned.\n\n{% hint style=\"info\" %}\n\n## Flat vs Nested response\n\n\nTwo options are supported for the response format.\n\n* Flat: The event and selection info are returned merged in a single object.\nThe results are sorted based on trending score.\n* Nested: The selections are returned group by their events, so if more than\none selections correspond to the same event, these will be grouped\nin the `selections` field of the given event object. Each event's\nselections are sorted based on trending score.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Trending score\n\n\nTo calculate trending score for a selection, each bet placed on this selection\ncontributes a value determined by how recently the bet was placed.\n\nRecent bets add more value than older ones.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Getting trending selections\n\n\nIn this example we get 10 trending selections for events played in China.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/selections/trending?count=10&filters=country%3Aeq%3AChina'\n```\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Availability of results\n\n\nNotice that if no bets for the available selections have been placed\nin the given time frame, no results will be returned.\n\n{% endhint %}\n\n","operationId":"get_trending_selections","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"Number of selections to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"maximum":100,"minimum":1,"type":"integer"}},{"description":"Comma separated list of event ids for which to return trending selections.\n","in":"query","name":"event_ids","required":false,"schema":{"type":"string"}},{"description":"Optional filtering on the events and markets to consider for the returned selections.\nIt expects a string adhering to the filtering format, as described in the filtering section,\ne.g. `sport:eq:Soccer;market:eq:1X2`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","participants","participant_ids","status","booking_status","event_type","market","market_id","market_type","market_type_id","outcome","outcome_id","market_status","market_group_status","trade_status","trade_market_status","quote","boosted_odds"],"type":"string"}},{"description":"The minimum event's starting datetime.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to 2 days.\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"Used to return results aggregated in the given market category.\nInstead of returning selections, this option allows to rank the markets on the given\naggregation type level. By default no aggregation will take place. Available options are:\n* `market_type_and_market`: Return selections aggregated on market type and market.\n* `market_type`: Return selections aggregated on market type.\n* `market`: Return selections aggregated on market.\n","in":"query","name":"aggregation_type","required":false,"schema":{"enum":["market_type_and_market","market_type","market"],"type":"string"}},{"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. `event_id,event_type`.\n","in":"query","name":"fields","required":false,"schema":{"default":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","score","count"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","score","count"],"type":"string"}},{"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","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"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","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"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","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Considers bets placed after the current timestamp minus the given\nminutes/hours/days. If not set defaults to `2 days`.\nThe value must be in range [1m - 7d].\n","in":"query","name":"trending_within","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/TrendingSelection"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get trending selections","tags":["Selections"]}}}}
````

## Get similar selections

> Returns similar selections for the given selection id(s).\
> \
> Similarity is measured for the selection's characteristics such as the\
> market type but also for the selection's underlying event.\
> \
> Only selections for events starting between the requested time range will be considered.\
> \
> {% hint style="info" %}\
> \
> \## Distance\
> \
> \
> The metric used to measure similarity between items is called distance.\
> It is a system indicator on how similar the item is to the input.\
> \
> The smaller the number the more similar the item.\
> \
> The normalized value of the item's distance to the input\
> is also assigned to each selection as its \`confidence\`.\
> \
> {% endhint %}\ <br>

```json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Selections related endpoints","name":"Selections"}],"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":{"SimilarSelection":{"additionalProperties":false,"description":"A similar selection object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"bet_offer_id":{"description":"The event specific market id","nullable":true,"type":"string"},"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"count":{"description":"How many bets are placed on the market","type":"integer"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"distance":{"description":"Distance of the item from the given inputs, the lowest the value the more\nsimilar the item.\n","type":"number"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"market":{"description":"The market's name","nullable":true,"type":"string"},"market_id":{"description":"The `market`'s id","nullable":true,"type":"number"},"market_type":{"description":"The market's type","nullable":true,"type":"string"},"market_type_id":{"description":"The `market_type`'s id","nullable":true,"type":"number"},"outcome":{"description":"The selection's outcome","nullable":true,"type":"string"},"outcome_id":{"description":"The `outcome`'s id","nullable":true,"type":"number"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"period":{"description":"The selection's period","nullable":true,"type":"string"},"period_id":{"description":"The `period`'s id","nullable":true,"type":"number"},"quote":{"description":"The selection's quote","type":"number"},"quote_group":{"description":"The group the quote belongs to","type":"string"},"selection_id":{"description":"The market selection id","type":"string"},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"},"uof_external_id":{"description":"The external market id","nullable":true,"type":"string"}},"type":"object"},"Error":{"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"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"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/sports/selections/similar":{"get":{"description":"Returns similar selections for the given selection id(s).\n\nSimilarity is measured for the selection's characteristics such as the\nmarket type but also for the selection's underlying event.\n\nOnly selections for events starting between the requested time range will be considered.\n\n{% hint style=\"info\" %}\n\n## Distance\n\n\nThe metric used to measure similarity between items is called distance.\nIt is a system indicator on how similar the item is to the input.\n\nThe smaller the number the more similar the item.\n\nThe normalized value of the item's distance to the input\nis also assigned to each selection as its `confidence`.\n\n{% endhint %}\n\n","operationId":"get_similar_selections","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"Comma separated list of selection ids for which to return similar selections.\n","in":"query","name":"selection_ids","required":true,"schema":{"type":"string"}},{"description":"Number of selections to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering on the events and markets to consider for the returned selections.\nIt expects a string adhering to the filtering format, as described in the filtering section,\ne.g. `sport:eq:Soccer;market:eq:1X2`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","participants","participant_ids","status","booking_status","event_type","market","market_id","market_type","market_type_id","outcome","outcome_id","market_status","market_group_status","trade_status","trade_market_status","quote","boosted_odds"],"type":"string"}},{"description":"The minimum event's starting datetime.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to 2 days.\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"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. `event_id,event_type`.\n","in":"query","name":"fields","required":false,"schema":{"default":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count","distance","confidence"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","count","distance","confidence"],"type":"string"}},{"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","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"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","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"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","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/SimilarSelection"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get similar selections","tags":["Selections"]}}}}
```

## Get sorted selections

> Ranks a specific set of selections for a given user. A \`confidence\` value\
> is assigned to each selections and the results are returned sorted by relevance.\
> \
> {% hint style="info" %}\
> \
> \## Endpoint usage\
> \
> \
> This endpoint should be used to rank a static set of selections, for example to\
> personalize the promoted selections of the day for each user. To get the most relevant\
> recommendations across all the available selections refer to \`get\_recommended\_selections\`.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Confidence\
> \
> \
> Each returned item is associated with a number from 0 to 1 indicating the confidence\
> of the system in this specific recommendation.\
> \
> The confidence is calculated based on both the event and market preferences\
> of the given selection.\
> \
> The higher the number the more confident the recommendation of it.\
> \
> {% endhint %}\ <br>

```json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Selections related endpoints","name":"Selections"}],"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":{"SortedSelection":{"additionalProperties":false,"description":"A sorted selection object","properties":{"begin":{"description":"The starting time of the event in UTC","format":"date-time","type":"string"},"bet_offer_id":{"description":"The event specific market id","nullable":true,"type":"string"},"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"event_id":{"description":"The unique event id","type":"string"},"event_type":{"description":"The type of the event, e.g. `outright","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"market":{"description":"The market's name","nullable":true,"type":"string"},"market_id":{"description":"The `market`'s id","nullable":true,"type":"number"},"market_type":{"description":"The market's type","nullable":true,"type":"string"},"market_type_id":{"description":"The `market_type`'s id","nullable":true,"type":"number"},"outcome":{"description":"The selection's outcome","nullable":true,"type":"string"},"outcome_id":{"description":"The `outcome`'s id","nullable":true,"type":"number"},"participant_ids":{"description":"The id of the event participants","items":{"type":"string"},"nullable":true,"type":"array"},"participants":{"description":"The participants of the event","items":{"type":"string"},"nullable":true,"type":"array"},"period":{"description":"The selection's period","nullable":true,"type":"string"},"period_id":{"description":"The `period`'s id","nullable":true,"type":"number"},"quote":{"description":"The selection's quote","type":"number"},"quote_group":{"description":"The group the quote belongs to","type":"string"},"selection_id":{"description":"The market selection id","type":"string"},"side":{"description":"The side of the market, back or lay (exchange only)","type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"status":{"description":"The status of the event, e.g. `live`","type":"string"},"uof_external_id":{"description":"The external market id","nullable":true,"type":"string"}},"type":"object"},"Error":{"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"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"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/sports/selections/sorted":{"get":{"description":"Ranks a specific set of selections for a given user. A `confidence` value\nis assigned to each selections and the results are returned sorted by relevance.\n\n{% hint style=\"info\" %}\n\n## Endpoint usage\n\n\nThis endpoint should be used to rank a static set of selections, for example to\npersonalize the promoted selections of the day for each user. To get the most relevant\nrecommendations across all the available selections refer to `get_recommended_selections`.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Confidence\n\n\nEach returned item is associated with a number from 0 to 1 indicating the confidence\nof the system in this specific recommendation.\n\nThe confidence is calculated based on both the event and market preferences\nof the given selection.\n\nThe higher the number the more confident the recommendation of it.\n\n{% endhint %}\n\n","operationId":"get_sorted_selections","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"Comma separated list of the selection ids to sort.","in":"query","name":"selection_ids","required":true,"schema":{"type":"string"}},{"description":"The user id.","in":"query","name":"user","required":true,"schema":{"type":"string"}},{"description":"Comma separated list of keywords. If given, this input will be used\nas user demographics data for the recommendations, e.g `country:gr,city:ath`.\n","in":"query","name":"raw","required":false,"schema":{"enum":["age_group","city","country"],"type":"string"}},{"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. `event_id,event_type`.\n","in":"query","name":"fields","required":false,"schema":{"default":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","confidence"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","selection_id","uof_external_id","bet_offer_id","market","market_id","market_type","market_type_id","outcome","outcome_id","period","period_id","quote","quote_group","side","confidence"],"type":"string"}},{"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","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"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","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"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","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"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`+begin,-event_confidence`.\n","in":"query","name":"order_by","required":false,"schema":{"enum":["begin","event_confidence","league_confidence","sport_confidence","country_confidence","event_id"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/SortedSelection"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get sorted selections","tags":["Selections"]}}}}
```


---

# 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/sports/selections.md?ask=<question>
```

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.