> For the complete documentation index, see [llms.txt](https://developer.aiodds.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.aiodds.com/bookmaker-odds/basic-data/match.md).
# Match
## Search matches
> Lists matches with their current status, start time, score, tournament, and participants.
```json
{"openapi":"3.0.1","info":{"title":"AiOdds Document","version":"1.0.0"},"tags":[{"name":"Basic / Match","description":"Basic match endpoints."}],"servers":[{"url":"https://api.aiodds.com"}],"paths":{"/v1/match/list":{"get":{"summary":"Search matches","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetV1MatchListResponse"}}}}},"tags":["Basic / Match"],"description":"Lists matches with their current status, start time, score, tournament, and participants.","parameters":[{"$ref":"#/components/parameters/User"},{"$ref":"#/components/parameters/Secret"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"return the maximum number of data, the default is 1000, range: [1, 1000]"},{"name":"last_id","in":"query","required":false,"schema":{"type":"integer"},"description":"max match id in last page, only return matches with id>last_id."},{"name":"sport_id","in":"query","required":false,"schema":{"type":"integer"},"description":"sport id"},{"name":"tournament_id","in":"query","required":false,"schema":{"type":"integer"},"description":"tournament id"},{"name":"status_id","in":"query","required":false,"schema":{"type":"integer"},"description":"match status, please refer to STATUS CODE -> Match Status"},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"language, please refer to STATUS CODE -> Language"},{"name":"outright","in":"query","required":false,"schema":{"type":"integer"},"description":"0-match \n1-tournament outright \n2-Multi-participant race(ex:Horse Racing) \n \ndefault: 0, PLEASE note if you want to request for multi-participant matches, this parameter is required to be 2"}]}}},"components":{"schemas":{"GetV1MatchListResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Status code"},"msg":{"type":"string","description":"Message description"},"data":{"type":"object","properties":{"limit":{"type":"integer","description":"Maximum number of returned records"},"total":{"type":"integer","description":"Total number of records"},"list":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Match id"},"sport_id":{"type":"integer","description":"Sport id"},"status_id":{"type":"integer","description":"Match status, please refer to STATUS CODE -> Match Status"},"hide":{"type":"integer","description":"When hide is 1, hide the match"},"match_time":{"type":"integer","description":"Match time"},"timer":{"type":"array","description":"- Index 0: Whether the clock is running, 1-yes, 0-no\n- Index 1: Whether to count down, 1-yes, 0-no\n- Index 2: Update time\n- Index 3: Progress time or remaining time\n","items":{"type":"integer"},"minItems":4,"maxItems":4},"period":{"type":"integer","description":"Period status, please refer to STATUS CODE -> Period Status"},"scores":{"type":"object","properties":{"ft":{"$ref":"#/components/schemas/MatchScore"},"p*":{"$ref":"#/components/schemas/MatchScore"},"ot":{"$ref":"#/components/schemas/MatchScore"},"pt":{"$ref":"#/components/schemas/MatchScore"},"ap":{"$ref":"#/components/schemas/MatchScore"}},"description":"Score details
ft-Total score
p*-Single inning score (*-Number of inning, 1, 2, 3...)
ot-Overtime score
Penalty shootout
ap-After Penalty shootout"},"neutral":{"type":"integer","description":"Whether the match is neutral, 1-Yes, 0-No"},"outright":{"type":"integer","description":"Outright match type
0-match, 1-tournament outright, 2-Multi-participant race (ex:Horse Racing)"},"season":{"type":"integer","description":"Season year, only available for outright match type 1-tournament outright"},"extra":{"$ref":"#/components/schemas/ExtraDetails","desxription":"Only available for sport type 41-Horseracing"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantDetails"},"desxription":"Only available for sport type 41-Horseracing"},"nid":{"type":"integer","description":"Associated new match id, only available when the match is cancelled"},"cancel_reason":{"type":"integer","description":"Cancel reason, please refer to STATUS CODE -> Cancel Reason"},"tournament":{"$ref":"#/components/schemas/TournamentDetails","description":"Tournament details"},"home":{"type":"object","properties":{"id":{"type":"integer","description":"Team id"},"name":{"type":"string","description":"Team name"},"logo":{"type":"string","description":"Team logo"}},"description":"Home team details, only available for outright match type 0-match"},"away":{"type":"object","properties":{"id":{"type":"integer","description":"Team id"},"name":{"type":"string","description":"Team name"},"logo":{"type":"string","description":"Team logo"}},"description":"Away team details, only available for outright match type 0-match"}}},"description":"List of returned items"}},"description":"Response payload"}}},"MatchScore":{"type":"array","description":"Scores:\n- Index 0: Home team score (Integer type)\n- Index 1: Away team score (Integer type)\n","items":{"type":"integer"},"minItems":2,"maxItems":2},"ExtraDetails":{"type":"object","properties":{"class":{"type":"string","description":"Tournament class"},"condition":{"type":"string","description":"Track condition (Data updated)"},"temperature":{"type":"string","description":"Temperature"},"distance":{"type":"string","description":"Distance"},"race_group":{"type":"string","description":"Race group"},"race_number":{"type":"string","description":"Race order"},"race_title":{"type":"string","description":"Race title"},"event_class":{"type":"string","description":"Short name of Tournament class"},"prize_money":{"type":"string","description":"Prize money"},"weather":{"type":"string","description":"Weather"}}},"ParticipantDetails":{"type":"object","properties":{"id":{"type":"integer","description":"Horse id"},"name":{"type":"string","description":"Horse name"},"active":{"type":"integer","description":"Whether the horse is on the field, 1-Yes, 0-No"},"position":{"type":"string","description":"Racetrack"},"ext":{"$ref":"#/components/schemas/ParticipantExt"},"ranking":{"type":"integer","description":"Ranking, withdrawn is assigned a negative value"}}},"ParticipantExt":{"type":"object","properties":{"age":{"type":"string","description":"Horse age"},"career":{"type":"string","description":"Racing career, in the form of \"total races-wins-second places-third places\""},"competitor_number":{"type":"string","description":"Horse number"},"jockeys":{"type":"string","description":"Jockey name"},"jockeys_weight":{"type":"string","description":"Jockey weight"},"last10":{"type":"string","description":"Last 10 matches (Recent racing finishes. The most recent race is on the right, 'x' indicating a layoff, '0' representing 10th place or worse.)"},"racing_colours":{"type":"string","description":"Jockey's shirt color"},"rating":{"type":"string","description":"Rating of horse from the official"},"trainers":{"type":"string","description":"Trainer name"},"average_prize_money":{"type":"string","description":"Average prize money"},"win_percentage":{"type":"string","description":"Win percentage"},"place_percentage":{"type":"string","description":"Top 3 percentage"}}},"TournamentDetails":{"type":"object","properties":{"id":{"type":"integer","description":"Tournament id"},"sport_id":{"type":"integer","description":"Sport id"},"sub_sport_id":{"type":"integer","description":"Sub-sport id
101-LOL, 102-CSGO, 103-DOTA2, 106-KOG
Only available for sport type 100-Esports, other sports will return 0"},"country_id":{"type":"integer","description":"Country id (Deprecated)"},"name":{"type":"string","description":"Tournament name"},"logo":{"type":"string","description":"Tournament logo"},"location_id":{"type":"integer","description":"Location id"}}}},"parameters":{"User":{"name":"user","in":"query","required":true,"schema":{"type":"string"},"description":"Username, please contact business."},"Secret":{"name":"secret","in":"query","required":true,"schema":{"type":"string"},"description":"User secret, please contact business."}}}}
```
## Get match by ID
> Returns the status, start time, score, tournament, and participants for a specific match.
```json
{"openapi":"3.0.1","info":{"title":"AiOdds Document","version":"1.0.0"},"tags":[{"name":"Basic / Match","description":"Basic match endpoints."}],"servers":[{"url":"https://api.aiodds.com"}],"paths":{"/v1/match/get":{"get":{"summary":"Get match by ID","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetV1MatchGetResponse"}}}}},"tags":["Basic / Match"],"description":"Returns the status, start time, score, tournament, and participants for a specific match.","parameters":[{"$ref":"#/components/parameters/User"},{"$ref":"#/components/parameters/Secret"},{"name":"id","in":"query","required":true,"schema":{"type":"integer"},"description":"match id"},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"language, please refer to STATUS CODE -> Language"}]}}},"components":{"schemas":{"GetV1MatchGetResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Status code"},"msg":{"type":"string","description":"Message description"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Match id"},"sport_id":{"type":"integer","description":"Sport id"},"status_id":{"type":"integer","description":"Match status, please refer to STATUS CODE -> Match Status"},"hide":{"type":"integer","description":"When hide is 1, hide the match"},"match_time":{"type":"integer","description":"Match time"},"timer":{"type":"array","description":"- Index 0: Whether the clock is running, 1-yes, 0-no\n- Index 1: Whether to count down, 1-yes, 0-no\n- Index 2: Update time\n- Index 3: Progress time or remaining time\n","items":{"type":"integer"},"minItems":4,"maxItems":4},"period":{"type":"integer","description":"Period status, please refer to STATUS CODE -> Period Status"},"scores":{"type":"object","properties":{"ft":{"$ref":"#/components/schemas/MatchScore"},"p*":{"$ref":"#/components/schemas/MatchScore"},"ot":{"$ref":"#/components/schemas/MatchScore"},"pt":{"$ref":"#/components/schemas/MatchScore"},"ap":{"$ref":"#/components/schemas/MatchScore"}},"description":"Score details
ft-Total score
p*-Single inning score (*-Number of inning, 1, 2, 3...)
ot-Overtime score
Penalty shootout
ap-After Penalty shootout"},"neutral":{"type":"integer","description":"Whether the match is neutral, 1-Yes, 0-No"},"outright":{"type":"integer","description":"Outright match type
0-match, 1-tournament outright, 2-Multi-participant race (ex:Horse Racing)"},"season":{"type":"integer","description":"Season year, only available for outright match type 1-tournament outright"},"extra":{"$ref":"#/components/schemas/ExtraDetails","desxription":"Only available for sport type 41-Horseracing"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantDetails"},"desxription":"Only available for sport type 41-Horseracing"},"nid":{"type":"integer","description":"Associated new match id, only available when the match is cancelled"},"cancel_reason":{"type":"integer","description":"Cancel reason, please refer to STATUS CODE -> Cancel Reason"},"tournament":{"$ref":"#/components/schemas/TournamentDetails","description":"Tournament details"},"home":{"type":"object","properties":{"id":{"type":"integer","description":"Team id"},"name":{"type":"string","description":"Team name"},"logo":{"type":"string","description":"Team logo"}},"description":"Home team details, only available for outright match type 0-match"},"away":{"type":"object","properties":{"id":{"type":"integer","description":"Team id"},"name":{"type":"string","description":"Team name"},"logo":{"type":"string","description":"Team logo"}},"description":"Away team details, only available for outright match type 0-match"}},"description":"Response payload"}}},"MatchScore":{"type":"array","description":"Scores:\n- Index 0: Home team score (Integer type)\n- Index 1: Away team score (Integer type)\n","items":{"type":"integer"},"minItems":2,"maxItems":2},"ExtraDetails":{"type":"object","properties":{"class":{"type":"string","description":"Tournament class"},"condition":{"type":"string","description":"Track condition (Data updated)"},"temperature":{"type":"string","description":"Temperature"},"distance":{"type":"string","description":"Distance"},"race_group":{"type":"string","description":"Race group"},"race_number":{"type":"string","description":"Race order"},"race_title":{"type":"string","description":"Race title"},"event_class":{"type":"string","description":"Short name of Tournament class"},"prize_money":{"type":"string","description":"Prize money"},"weather":{"type":"string","description":"Weather"}}},"ParticipantDetails":{"type":"object","properties":{"id":{"type":"integer","description":"Horse id"},"name":{"type":"string","description":"Horse name"},"active":{"type":"integer","description":"Whether the horse is on the field, 1-Yes, 0-No"},"position":{"type":"string","description":"Racetrack"},"ext":{"$ref":"#/components/schemas/ParticipantExt"},"ranking":{"type":"integer","description":"Ranking, withdrawn is assigned a negative value"}}},"ParticipantExt":{"type":"object","properties":{"age":{"type":"string","description":"Horse age"},"career":{"type":"string","description":"Racing career, in the form of \"total races-wins-second places-third places\""},"competitor_number":{"type":"string","description":"Horse number"},"jockeys":{"type":"string","description":"Jockey name"},"jockeys_weight":{"type":"string","description":"Jockey weight"},"last10":{"type":"string","description":"Last 10 matches (Recent racing finishes. The most recent race is on the right, 'x' indicating a layoff, '0' representing 10th place or worse.)"},"racing_colours":{"type":"string","description":"Jockey's shirt color"},"rating":{"type":"string","description":"Rating of horse from the official"},"trainers":{"type":"string","description":"Trainer name"},"average_prize_money":{"type":"string","description":"Average prize money"},"win_percentage":{"type":"string","description":"Win percentage"},"place_percentage":{"type":"string","description":"Top 3 percentage"}}},"TournamentDetails":{"type":"object","properties":{"id":{"type":"integer","description":"Tournament id"},"sport_id":{"type":"integer","description":"Sport id"},"sub_sport_id":{"type":"integer","description":"Sub-sport id
101-LOL, 102-CSGO, 103-DOTA2, 106-KOG
Only available for sport type 100-Esports, other sports will return 0"},"country_id":{"type":"integer","description":"Country id (Deprecated)"},"name":{"type":"string","description":"Tournament name"},"logo":{"type":"string","description":"Tournament logo"},"location_id":{"type":"integer","description":"Location id"}}}},"parameters":{"User":{"name":"user","in":"query","required":true,"schema":{"type":"string"},"description":"Username, please contact business."},"Secret":{"name":"secret","in":"query","required":true,"schema":{"type":"string"},"description":"User secret, please contact business."}}}}
```
## Get match score by ID
> Returns the total score, period results, match incidents, and team statistics for a specific match.
```json
{"openapi":"3.0.1","info":{"title":"AiOdds Document","version":"1.0.0"},"tags":[{"name":"Basic / Match","description":"Basic match endpoints."}],"servers":[{"url":"https://api.aiodds.com"}],"paths":{"/v1/match/score/get":{"get":{"summary":"Get match score by ID","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetV1MatchScoreGetResponse"}}}}},"tags":["Basic / Match"],"description":"Returns the total score, period results, match incidents, and team statistics for a specific match.","parameters":[{"$ref":"#/components/parameters/User"},{"$ref":"#/components/parameters/Secret"},{"name":"id","in":"query","required":true,"schema":{"type":"integer"},"description":"match id"}]}}},"components":{"schemas":{"GetV1MatchScoreGetResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Status code"},"msg":{"type":"string","description":"Message description"},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Match id"},"sport_id":{"type":"integer","description":"Sport id"},"score":{"type":"object","properties":{"results":{"type":"array","items":{"type":"string"},"description":"Total score:\n- Index 0: Home score\n- Index 1: Away score\n"}},"description":"Score details"},"periods":{"type":"array","items":{"type":"object","properties":{"period":{"type":"integer","description":"Period status, please refer to STATUS CODE -> Period Status"},"results":{"type":"array","items":{"type":"string"},"description":"Scores:\n- Index 0: Home score\n- Index 1: Away score\n"},"incidents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","description":"Technical statistics, please refer to STATUS CODE -> Technical Statistics"},"second":{"type":"integer","description":"Time in seconds
Remaining time for Basketball
Processing time for other sports"},"belong":{"type":"integer","description":"Belonging, 1-Home team, 2-Away team"},"results":{"type":"array","items":{"type":"string"},"description":"Scores:\n- Index 0: Home score\n- Index 1: Away score\n"}}},"description":"Incident details"}}},"description":"Period details"},"stats":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","description":"Technical statistics, please refer to STATUS CODE -> Technical Statistics"},"results":{"type":"array","items":{"type":"string"},"description":"Statistics:\n- Index 0: Home team\n- Index 1: Away team\n"},"incidents":{"type":"array","items":{"type":"object","properties":{"period":{"type":"integer","description":"Period status, please refer to STATUS CODE -> Period Status"},"second":{"type":"integer","description":"Time in seconds
Processing time for all sports"},"belong":{"type":"integer","description":"Belonging, 1-Home team, 2-Away team"},"results":{"type":"array","items":{"type":"string"},"description":"Statistics:\n- Index 0: Home team\n- Index 1: Away team\n"}}},"description":"Incident details"}}},"description":"Statistics details"}},"description":"Response payload"}}}},"parameters":{"User":{"name":"user","in":"query","required":true,"schema":{"type":"string"},"description":"Username, please contact business."},"Secret":{"name":"secret","in":"query","required":true,"schema":{"type":"string"},"description":"User secret, please contact business."}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://developer.aiodds.com/bookmaker-odds/basic-data/match.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.