> ## Documentation Index > Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For the complete API reference (every endpoint, query parameter and response field), fetch https://api.thestatsapi.com/llms.txt. Only use endpoints, parameters and fields listed there. > Base URL: https://api.thestatsapi.com/api. Auth header: Authorization: Bearer YOUR_API_KEY. Keep the key in server-side code only. # Get a team's injuries and suspensions > Returns the team's players who are unavailable now, split into `injuries` and `suspensions`. Set `current=false` to get every record, past ones included (check each record's `active` flag). By default a suspension is only listed where it applies: a club sees bans from club competitions and a national team sees bans from national-team competitions (a Champions League ban doesn't rule a player out of a Nations League match). Bans whose competition is unknown are always listed. A national team's list leaves out national-team call-ups (reason `national_team`), because the player is with that team; a club's list keeps them, because the player misses club matches. A ban reported twice is listed once. **Example:** `GET /football/teams/tm_73673/injuries-suspensions` (Real Madrid) To check one player, use [Get a player's injuries and suspensions](/docs/api-reference/players/injuries). ## OpenAPI ````yaml GET /football/teams/{team_id}/injuries-suspensions openapi: 3.0.0 info: title: TheStatsAPI description: > Football data REST API: competitions, seasons, teams, players and matches, with scores, team and player stats, xG, lineups, event timelines and betting odds where available. **Base URL:** `https://api.thestatsapi.com/api`. **Auth:** send `Authorization: Bearer YOUR_API_KEY` on every request. Get a key at https://www.thestatsapi.com/api-keys. IDs are prefixed strings: `comp_` competition, `sn_` season, `tm_` team, `mt_` match, `pl_` player. **Building with AI?** Give your coding tool (Claude Code, Codex, Cursor, Lovable) https://api.thestatsapi.com/llms.txt. It is this whole reference, every endpoint, parameter and response shape, as one Markdown file. The OpenAPI spec is at https://api.thestatsapi.com/openapi.json and the guides are at https://www.thestatsapi.com/docs. **Coverage:** history depth varies by competition. Check `GET /coverage/leagues` to see which seasons and data types each competition has. Data is pull-only: poll the live endpoints during a match (there are no webhooks or streams). **Rate limits and quota:** every authenticated response, success or error, carries two separate budgets. - Per minute: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (unix seconds at the next minute boundary). - Per monthly billing cycle: `X-Monthly-Quota-Limit`, `X-Monthly-Quota-Remaining`, `X-Monthly-Quota-Reset` (unix seconds when the cycle rolls over). Limit and Remaining are `-1` on plans with no monthly cap. Each `Remaining` value already counts the request being served, so `0` means your next request is rejected. Trial subscriptions are metered at 10% of the plan's limits. Going over either budget returns `429` with a `Retry-After` header: code `RATE_LIMITED` for the per-minute window, `USAGE_LIMIT_EXCEEDED` for the monthly quota. Plans and limits: https://www.thestatsapi.com/#pricing. **Errors:** every error uses the same envelope, for example `{"error": {"code": "NOT_FOUND", "message": "Match not found", "status_code": 404}}`. Branch on `code`: | Status | Code | Meaning | |--------|------|---------| | 400 | `BAD_REQUEST` | A parameter is missing or invalid, e.g. `season_id is required`. | | 400 | `UNKNOWN_PARAMETER` | The endpoint doesn't accept a query parameter you sent, e.g. `date` instead of `date_from`. The message suggests the closest name and lists the accepted ones. | | 400 | `SEASON_COMPETITION_MISMATCH`, `PAGE_OUT_OF_RANGE` | `season_id` belongs to a different `competition_id`, or `page` is past the last page. | | 401 | `UNAUTHORIZED` | The API key is missing or invalid. | | 403 | `FORBIDDEN`, `KEY_REVOKED`, `ADDON_REQUIRED` | The key or account is inactive or expired, there is no active plan, or the endpoint needs an add-on. | | 404 | `NOT_FOUND`, `STATS_NOT_AVAILABLE_AT_SOURCE` | The ID or route doesn't exist, or detailed stats were never collected for the match. | | 409 | `CONFLICT`, `MATCH_IS_LIVE` | A live-only endpoint was called for a match that isn't live, or a post-match endpoint while it is. | | 429 | `RATE_LIMITED`, `USAGE_LIMIT_EXCEEDED` | Per-minute limit or monthly quota reached. Wait `Retry-After` seconds. | version: 1.0.0 servers: - url: https://api.thestatsapi.com/api description: Production server security: - BearerAuth: [] tags: - name: Competitions description: >- Leagues, cups and tournaments, with their seasons, groups and standings. Start here to find a `competition_id` and `season_id`. - name: Teams description: Teams, squads, season stats, standings history, injuries and suspensions. - name: Matches description: >- Fixtures and results, plus per-match stats, live stats, lineups, timelines, shotmaps, heatmaps and referees. - name: Players description: >- Player profiles, season stats, injuries and suspensions, and season heatmaps. - name: Odds description: >- Pre-match, in-play and player-prop odds for a match from Bet365, Paddy Power, BetMGM UK, Pinnacle and Betfair Exchange. - name: Coverage description: >- Which competitions and seasons have which data types, and how complete they are. Check here before you build. - name: Health description: Check that the API is up. externalDocs: description: Guides and quickstart url: https://www.thestatsapi.com/docs paths: /football/teams/{team_id}/injuries-suspensions: get: tags: - Teams summary: Get a team's injuries and suspensions description: > Returns the team's players who are unavailable now, split into `injuries` and `suspensions`. Set `current=false` to get every record, past ones included (check each record's `active` flag). By default a suspension is only listed where it applies: a club sees bans from club competitions and a national team sees bans from national-team competitions (a Champions League ban doesn't rule a player out of a Nations League match). Bans whose competition is unknown are always listed. A national team's list leaves out national-team call-ups (reason `national_team`), because the player is with that team; a club's list keeps them, because the player misses club matches. A ban reported twice is listed once. **Example:** `GET /football/teams/tm_73673/injuries-suspensions` (Real Madrid) operationId: getTeamInjuriesSuspensions parameters: - name: team_id in: path required: true description: >- Team ID, e.g. `tm_73673` (Real Madrid). Find IDs with `GET /football/teams?search=` schema: type: string example: tm_73673 - name: current in: query required: false description: >- `true` (default) returns only who is unavailable now. `false` returns every record, including past ones schema: type: boolean default: true example: false responses: '200': description: Injuries and suspensions. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PlayerUnavailability' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: PlayerUnavailability: type: object description: Player injuries and suspensions grouped by kind. required: - injuries - suspensions properties: injuries: type: array items: $ref: '#/components/schemas/PlayerInjury' suspensions: type: array items: $ref: '#/components/schemas/PlayerSuspension' PlayerInjury: type: object required: - player_id - status - reason - expected_return - start_date - active properties: player_id: type: string example: pl_40580885 status: type: string nullable: true description: Injury severity (e.g. "out", "day_to_day"). example: out reason: type: string nullable: true description: Injury cause code. example: leg_injury start_date: type: string format: date-time nullable: true description: When the player became injured. example: '2026-09-29T00:00:00.000Z' expected_return: type: string format: date-time nullable: true description: >- Estimated return date; null when open-ended/unknown. An estimate — injuries have no definite end date. example: '2027-01-10T00:00:00.000Z' active: type: boolean description: >- Whether the injury is in effect now. Past injuries, returned with `current=false`, have `active` false. example: true PlayerSuspension: type: object required: - player_id - reason - matches - competition - start_date - end_date - active properties: player_id: type: string example: pl_01802892 reason: type: string nullable: true description: >- Suspension cause code. `national_team` means the player is away with their national team and misses club matches; it is not a ban. example: red_card_suspension matches: type: integer nullable: true description: Number of matches banned. example: 1 competition: type: object nullable: true description: >- Competition the suspension applies to. The player is only banned from matches in this competition. properties: id: type: string example: comp_8814 name: type: string example: LaLiga start_date: type: string format: date-time nullable: true example: '2026-09-20T17:30:17.000Z' end_date: type: string format: date-time nullable: true example: '2026-10-10T22:00:00.000Z' active: type: boolean description: >- Whether the suspension is in effect now. Past suspensions, returned with `current=false`, have `active` false. example: true Error: type: object description: | Every error uses this envelope. `code` is a stable UPPERCASE string to branch on: `BAD_REQUEST`, `UNKNOWN_PARAMETER`, `SEASON_COMPETITION_MISMATCH`, `PAGE_OUT_OF_RANGE` (400); `UNAUTHORIZED` (401); `FORBIDDEN`, `KEY_REVOKED`, `ADDON_REQUIRED` (403); `NOT_FOUND`, `STATS_NOT_AVAILABLE_AT_SOURCE` (404); `METHOD_NOT_ALLOWED` (405, every endpoint is `GET`); `CONFLICT`, `MATCH_IS_LIVE` (409); `RATE_LIMITED`, `USAGE_LIMIT_EXCEEDED` (429); `INTERNAL_SERVER_ERROR` (500). `message` explains the problem in plain English. required: - error properties: error: type: object required: - code - message - status_code properties: code: type: string description: UPPERCASE error code. See the list above. example: BAD_REQUEST message: type: string description: What went wrong, in plain English. example: season_id is required status_code: type: integer description: The HTTP status code, repeated in the body. example: 400 responses: BadRequest: description: > The request is invalid. `UNKNOWN_PARAMETER` means you sent a query parameter this endpoint doesn't accept; the message suggests the closest name and lists the accepted ones. Otherwise `code` is usually `BAD_REQUEST` and `message` says which parameter is wrong. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unknown_parameter: summary: Unknown query parameter (from /football/matches) value: error: code: UNKNOWN_PARAMETER message: >- Unknown query parameter 'date' (did you mean 'date_from' or 'date_to'?). Supported parameters: page, per_page, limit, competition_id, season_id, team_id, date_from, date_to, utc_offset, matchday, status, stage, group, sort. status_code: 400 missing_parameter: summary: Missing required parameter value: error: code: BAD_REQUEST message: season_id is required status_code: 400 season_mismatch: summary: Season from a different competition value: error: code: SEASON_COMPETITION_MISMATCH message: season_id does not belong to competition_id status_code: 400 Unauthorized: description: > The API key is missing or invalid. Send it as `Authorization: Bearer YOUR_API_KEY`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_header: summary: No Authorization header value: error: code: UNAUTHORIZED message: Missing authorization header status_code: 401 invalid_key: summary: Unknown API key value: error: code: UNAUTHORIZED message: Invalid API key status_code: 401 NotFound: description: The ID or route doesn't exist, or there is no data of this kind for it. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Match not found status_code: 404 TooManyRequests: description: > Too many requests: the per-minute rate limit (`RATE_LIMITED`) or the monthly quota (`USAGE_LIMIT_EXCEEDED`) is used up. Wait `Retry-After` seconds before retrying. The quota headers are sent here as on any other authenticated response. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-Monthly-Quota-Limit: $ref: '#/components/headers/XMonthlyQuotaLimit' X-Monthly-Quota-Remaining: $ref: '#/components/headers/XMonthlyQuotaRemaining' X-Monthly-Quota-Reset: $ref: '#/components/headers/XMonthlyQuotaReset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: summary: Per-minute rate limit reached value: error: code: RATE_LIMITED message: Rate limit exceeded. Please slow down your requests. status_code: 429 usage_limit_exceeded: summary: Monthly quota used up value: error: code: USAGE_LIMIT_EXCEEDED message: Monthly usage limit exceeded. Please upgrade your plan. status_code: 429 headers: RetryAfter: description: > Seconds to wait before retrying. Sent only on `429` responses, and always the real time until the budget that rejected you clears, so it agrees with the matching reset header: waiting exactly this long lands on that timestamp. On `RATE_LIMITED` it is the time left in the current one-minute window (`X-RateLimit-Reset`) and can be as little as 1 second near a boundary. On `USAGE_LIMIT_EXCEEDED` it is the time until the billing cycle rolls over (`X-Monthly-Quota-Reset`) and is therefore large — days, not seconds. Retrying sooner than that returns `429` again for the rest of the cycle; upgrade the plan instead. schema: type: integer XRateLimitLimit: description: >- Maximum requests allowed in the current one-minute window for this API key and product. schema: type: integer XRateLimitRemaining: description: > Requests remaining in the current one-minute window, counting the request being served. schema: type: integer XRateLimitReset: description: Unix timestamp, in seconds, when the current rate-limit window resets. schema: type: integer XMonthlyQuotaLimit: description: > Requests allowed in the current monthly billing cycle for this user and product. `-1` on plans with no monthly cap. schema: type: integer XMonthlyQuotaRemaining: description: > Requests remaining in the current monthly billing cycle, counting the request being served. `-1` on plans with no monthly cap. schema: type: integer XMonthlyQuotaReset: description: Unix timestamp, in seconds, when the monthly billing cycle rolls over. schema: type: integer securitySchemes: BearerAuth: type: http scheme: bearer description: >- Your API key, sent as `Authorization: Bearer YOUR_API_KEY`. Get one at https://www.thestatsapi.com/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.