# Events

Sport events related endpoints

## Get recommended events

> Returns personalized event recommendations. Only events starting between\
> the requested time range will be considered.\
> \
> {% 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 higher the number the more confident\
> the recommendation of it.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Result ordering\
> \
> \
> By default events are sorted based on confidence, with the most\
> confident one on top. The \`order\_by\` parameter can be used\
> to order the results in the desired order.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Picking the correct date parameters\
> \
> \
> To best utilize the endpoint and its caching mechanisms, it is advised\
> to use the \`from\` parameter only when requesting items for a specific\
> datetime, e.g \`2021-12-25 19:45:00\`. To query for the current datetime\
> plus/minus a given amount, it is heavily recommended to avoid using\
> \`from\` and use the \`from\_offset\` parameter instead.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Getting live recommended events\
> \
> \
> In this example we get all recommended events for the user with id \`1\`\
> where \`status\` is \`live\`. Notice the \`from\_offset\` parameter that should be\
> provided with a negative value, to return events that are already live\
> for a maximum of 2 hours.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/events/recommended?user=1\\&filters=status%3Aeq%3Alive\\&from\\_offset=-2h'\\>
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport events related endpoints","name":"Events"}],"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":{"RecommendedEvent":{"oneOf":[{"description":"Array of recommended events","items":{"additionalProperties":false,"description":"A recommended event 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"},"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"},"type":"array"},{"additionalProperties":false,"description":"The kambi recommended response","properties":{"coupon_tool_selections":{"description":"List of objects with the league ids","items":{"type":"object"},"type":"array"},"events":{"description":"List with the recommended events and their bet offers","items":{"type":"object"},"type":"array"},"name":{"description":"A generic name for the response","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/events/recommended":{"get":{"description":"Returns personalized event recommendations. Only events starting between\nthe requested time range will be considered.\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. The higher the number the more confident\nthe recommendation of it.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Result ordering\n\n\nBy default events are sorted based on confidence, with the most\nconfident one on top. The `order_by` parameter can be used\nto order the results in the desired order.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Picking the correct date parameters\n\n\nTo best utilize the endpoint and its caching mechanisms, it is advised\nto use the `from` parameter only when requesting items for a specific\ndatetime, e.g `2021-12-25 19:45:00`. To query for the current datetime\nplus/minus a given amount, it is heavily recommended to avoid using\n`from` and use the `from_offset` parameter instead.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Getting live recommended events\n\n\nIn this example we get all recommended events for the user with id `1`\nwhere `status` is `live`. Notice the `from_offset` parameter that should be\nprovided with a negative value, to return events that are already live\nfor a maximum of 2 hours.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/events/recommended?user=1&filters=status%3Aeq%3Alive&from_offset=-2h'\n```\n\n{% endhint %}\n\n","operationId":"get_recommended_events","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 to get recommendations for.","in":"query","name":"user","required":true,"schema":{"type":"string"}},{"description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","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 one day (24 hours).\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":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":100,"minimum":1,"type":"integer"}},{"description":"Excludes the top `n` popular events from the results.\n","in":"query","name":"exclude_n_popular","required":false,"schema":{"default":0,"type":"integer"}},{"description":"Optional filtering of the events to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids","user_country","user_city","user_state","user_age_group","user_gender"],"type":"string"}},{"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 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":"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":"Applies prioritization limits to a group of items. The limited items are ensured\nto be present in the response. It expects a string adhering to the `prioritized_limit`\nformat, e.g. `field:value_1=2,value_2=4`. For more information head to the\n`Limiting -> Prioritized limiting` section of the docs.\n","in":"query","name":"prioritized_limit","required":false,"schema":{"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status"],"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":"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":"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","confidence","league_confidence","sport_confidence","country_confidence"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","confidence","league_confidence","sport_confidence","country_confidence"],"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":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"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","country","country_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":{"$ref":"#/components/schemas/RecommendedEvent"},"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 events","tags":["Events"]}}}}
````

## Get popular events

> Returns popular events for the given time frame.\
> \
> The events are sorted by popularity.\
> \
> {% hint style="info" %}\
> \
> \## Popularity\
> \
> \
> The metric used to measure popularity is the number of bets placed on each event.\
> \
> The normalized value of its total bets is also assigned to each event as its confidence.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Filtering example\
> \
> \
> In this example we get all popular events where \`league\` is \`UEFA Champions League\`.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/events/popular?filters=league%3Aeq%3AUEFA%20Champions%20League'\\>
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport events related endpoints","name":"Events"}],"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":{"PopularEvent":{"additionalProperties":false,"description":"A popular event 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_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"},"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"},"total_bets":{"description":"Number of bets including this event","type":"integer"}},"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/events/popular":{"get":{"description":"Returns popular events for the given time frame.\n\nThe events are sorted by popularity.\n\n{% hint style=\"info\" %}\n\n## Popularity\n\n\nThe metric used to measure popularity is the number of bets placed on each event.\n\nThe normalized value of its total bets is also assigned to each event as its confidence.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Filtering example\n\n\nIn this example we get all popular events where `league` is `UEFA Champions League`.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/events/popular?filters=league%3Aeq%3AUEFA%20Champions%20League'\n```\n\n{% endhint %}\n\n","operationId":"get_popular_events","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 to get recommendations for.","in":"query","name":"user","required":false,"schema":{"type":"string"}},{"description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","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 one day (24 hours).\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":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":100,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the events to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids","user_country","user_city","user_state","user_age_group","user_gender","shop_id","shop_country_code","shop_region","terminal_id"],"type":"string"}},{"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 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":"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":"Optional dynamic filtering of the items to retrieve. If any dynamic filter is set,\nthe filter's value will be dynamically calculated and used. Notice that for `user`\nrelated filters, the `user` query parameter must be provided. For example,\n`dynamic_filters=user_country` will return data related only to the user's specific country.\n","in":"query","name":"dynamic_filters","required":false,"schema":{"enum":["user_country","user_state","user_language","user_brand","user_city","game_country"],"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":"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. `recommended:0.3,trending:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["recommended","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":"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","confidence","total_bets"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","confidence","total_bets"],"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/PopularEvent"},"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 events","tags":["Events"]}}}}
````

## Get trending events

> Returns trending events for the given time frame.\
> \
> The events are sorted by \`trending score\`.\
> \
> {% hint style="info" %}\
> \
> \## Trending score\
> \
> \
> To calculate trending score for an event, each bet placed on this event\
> contributes a value determined by how recently the bet was placed.\
> \
> Recent bets add more value than older ones.\
> \
> The normalized value of its score is also assigned to each event as its confidence.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Filtering example\
> \
> \
> In this example we get all trending events where \`league\` is \`UEFA Champions League\`.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/events/trending?filters=league%3Aeq%3AUEFA%20Champions%20League'\\>
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport events related endpoints","name":"Events"}],"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":{"TrendingEvent":{"additionalProperties":false,"description":"A trending event 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_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"},"score":{"description":"Trending score, the highest the score the more trending the item","type":"number"},"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"},"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/events/trending":{"get":{"description":"Returns trending events for the given time frame.\n\nThe events are sorted by `trending score`.\n\n{% hint style=\"info\" %}\n\n## Trending score\n\n\nTo calculate trending score for an event, each bet placed on this event\ncontributes a value determined by how recently the bet was placed.\n\nRecent bets add more value than older ones.\n\nThe normalized value of its score is also assigned to each event as its confidence.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Filtering example\n\n\nIn this example we get all trending events where `league` is `UEFA Champions League`.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/events/trending?filters=league%3Aeq%3AUEFA%20Champions%20League'\n```\n\n{% endhint %}\n\n","operationId":"get_trending_events","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 to get recommendations for.","in":"query","name":"user","required":false,"schema":{"type":"string"}},{"description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","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 one day (24 hours).\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":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":100,"minimum":1,"type":"integer"}},{"description":"Excludes the top `n` popular events from the results.\n","in":"query","name":"exclude_n_popular","required":false,"schema":{"default":0,"type":"integer"}},{"description":"Optional filtering of the events to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids","user_country","user_city","user_state","user_age_group","user_gender"],"type":"string"}},{"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 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":"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":"Optional dynamic filtering of the items to retrieve. If any dynamic filter is set,\nthe filter's value will be dynamically calculated and used. Notice that for `user`\nrelated filters, the `user` query parameter must be provided. For example,\n`dynamic_filters=user_country` will return data related only to the user's specific country.\n","in":"query","name":"dynamic_filters","required":false,"schema":{"enum":["user_country","user_state","user_language","user_brand","user_city","game_country"],"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":"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. `recommended:0.3,popular:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["recommended","popular"],"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":"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","confidence","score"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","confidence","score"],"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"}},{"description":"The sports inference query type. If `events` the query will use the `users_event`\nand `users_bet` tables to calculate the total bets for each event,\ndistinct per `player_id, event_id`. If `stats_events` the query will use the\npre-populated table `stats_event`. To use this option make sure that the stats_events\ntable exists and is being updated since not all operator support it. If\n`total_counts` the query will count all bets per event, without de-duplicating\nby `player_id, event_id`.\n\nNote: `stats_events` option doesn't support user demographic filters.\n","in":"query","name":"query_type","required":false,"schema":{"default":"events","enum":["events","stats_events","total_counts"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/TrendingEvent"},"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 events","tags":["Events"]}}}}
````

## Get similar events

> Returns similar events for the given event id(s). Only events starting between\
> the requested time range will be considered.\
> \
> The events are sorted by \`distance\` ascending.\
> \
> {% 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 %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Query example\
> \
> \
> In this example we get the similar events to the event with id \`SBTE\_25008061\`\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/events/similar?event\\_ids=SBTE\\_25008061'\\>
> \`\`\`\
> \
> {% endhint %}\
> \
> \
> \
> {% hint style="info" %}\
> \
> \## Getting live similar events\
> \
> \
> In this example we get \`live\` events similar to the event with id \`SBTE\_25008061\`.\
> Notice the \`from\_offset\` parameter that should be provided with a negative value,\
> to return events that are already live for a maximum of 3 hours.\
> \
> \`\`\`bash\
> $ curl --request GET \\\
> &#x20; \--url '<https://api.vaix.ai/api/sports/events/similar?event\\_ids=SBTE\\_25008061\\&filters=status%3Aeq%3Alive\\&from\\_offset=-3h'\\>
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport events related endpoints","name":"Events"}],"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":{"SimilarEvent":{"description":"A similar event 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_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"},"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"},"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"},"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/events/similar":{"get":{"description":"Returns similar events for the given event id(s). Only events starting between\nthe requested time range will be considered.\n\nThe events are sorted by `distance` ascending.\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\n{% hint style=\"info\" %}\n\n## Query example\n\n\nIn this example we get the similar events to the event with id `SBTE_25008061`\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/events/similar?event_ids=SBTE_25008061'\n```\n\n{% endhint %}\n\n\n\n{% hint style=\"info\" %}\n\n## Getting live similar events\n\n\nIn this example we get `live` events similar to the event with id `SBTE_25008061`.\nNotice the `from_offset` parameter that should be provided with a negative value,\nto return events that are already live for a maximum of 3 hours.\n\n```bash\n$ curl --request GET \\\n  --url 'https://api.vaix.ai/api/sports/events/similar?event_ids=SBTE_25008061&filters=status%3Aeq%3Alive&from_offset=-3h'\n```\n\n{% endhint %}\n\n","operationId":"get_similar_events","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 event ids for which to return similar events.\nIf multiple events are provided the events returned are going to be\nthe ones with the shortest average distance to all of the provided events.\n","in":"query","name":"event_ids","required":true,"schema":{"type":"string"}},{"description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","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 one day (24 hours).\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":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":100,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the events to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids"],"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 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":"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","confidence","distance"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","confidence","distance"],"type":"string"}},{"description":"If it's true include input items in response. By default is set to `false`.\n","in":"query","name":"include_input","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"If `true`, ensures that all participants will be unique in respect to the\ninput events' participants. Defaults to `false`.\n","in":"query","name":"unique_participants","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"The sports inference query type. If `events` the query will use the `users_event`\nand `users_bet` tables to calculate the total bets for each event,\ndistinct per `player_id, event_id`. If `stats_events` the query will use the\npre-populated table `stats_event`. To use this option make sure that the stats_events\ntable exists and is being updated since not all operator support it. If\n`total_counts` the query will count all bets per event, without de-duplicating\nby `player_id, event_id`.\n\nNote: `stats_events` option doesn't support user demographic filters.\n","in":"query","name":"query_type","required":false,"schema":{"default":"events","enum":["events","stats_events","total_counts"],"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/SimilarEvent"},"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 events","tags":["Events"]}}}}
````

## Get frequently combined events

> Returns events that the players who have placed bets on the event with the given\
> \`event\_id\` have also placed bets on (not necessarily in the same betslip).<br>

```json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport events related endpoints","name":"Events"}],"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":{"CombinedEvent":{"additionalProperties":false,"description":"A frequently combined events response.","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"},"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"},"times_combined":{"description":"Number of players who have combined this event","type":"integer"}},"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/events/combined":{"get":{"description":"Returns events that the players who have placed bets on the event with the given\n`event_id` have also placed bets on (not necessarily in the same betslip).\n","operationId":"get_combined_events","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 event id for which we seek frequently combined events.","in":"query","name":"event_id","required":true,"schema":{"type":"string"}},{"description":"The minimum event's starting datetime. If not explicitly set it defaults to `now`.","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 one day (24 hours).\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":"Number of events to return.\n","in":"query","name":"count","required":false,"schema":{"default":100,"minimum":1,"type":"integer"}},{"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":"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","times_combined"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","times_combined"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Optional filtering of the events to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["sport","sport_id","country","country_id","league","league_id","status","booking_status","event_type","participants","participant_ids"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/CombinedEvent"},"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 frequently combined events","tags":["Events"]}}}}
```

## Sort list of events

> Ranks a specific set of events for a given user. A \`confidence\` value\
> is assigned to each event and the results are returned sorted by relevance.\
> \
> {% hint style="info" %}\
> \
> \## Endpoint usage\
> \
> \
> This endpoint should be used to rank a static set of events, for example to\
> personalize the promoted events of the day for each user. To get the most relevant\
> recommendations across all the available events refer to \`get\_recommended\_events\`.\
> \
> {% 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 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":"Sport events related endpoints","name":"Events"}],"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":{"RecommendedEventVaix":{"additionalProperties":false,"description":"A recommended event 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"},"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/events/sorted":{"get":{"description":"Ranks a specific set of events for a given user. A `confidence` value\nis assigned to each event 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 events, for example to\npersonalize the promoted events of the day for each user. To get the most relevant\nrecommendations across all the available events refer to `get_recommended_events`.\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. The higher the number the more confident\nthe recommendation of it.\n\n{% endhint %}\n\n","operationId":"get_sorted_events","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 to get recommendations for.","in":"query","name":"user","required":true,"schema":{"type":"string"}},{"description":"Comma separated list of event ids to rank.","in":"query","name":"event_ids","required":true,"schema":{"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":"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","confidence"],"enum":["event_id","event_type","begin","country","country_id","league","league_id","sport","sport_id","participants","participant_ids","status","confidence"],"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"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/RecommendedEventVaix"},"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":"Sort list of events","tags":["Events"]}}}}
```


---

# 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/events.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.