> ## 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 coverage totals

> Returns headline totals across all competitions: number of competitions, seasons and finished matches, and seasons by status.

**Example:** `GET /coverage/summary`


For per-competition detail, use [List coverage by competition](/docs/api-reference/coverage/leagues). See [Coverage](/docs/concepts/coverage).


## OpenAPI

````yaml GET /coverage/summary
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:
  /coverage/summary:
    get:
      tags:
        - Coverage
      summary: Get coverage totals
      description: >
        Returns headline totals across all competitions: number of competitions,
        seasons and finished matches, and seasons by status.


        **Example:** `GET /coverage/summary`
      operationId: getCoverageSummary
      responses:
        '200':
          description: Coverage totals.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CoverageSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    CoverageSummary:
      type: object
      properties:
        leagues:
          type: integer
          example: 204
        seasons:
          type: integer
          example: 1107
        finished_events:
          type: integer
          example: 202269
        seasons_by_status:
          type: object
          properties:
            complete:
              type: integer
              example: 922
            in_progress:
              type: integer
              example: 152
            not_loaded:
              type: integer
              example: 33
        pct_complete:
          type: number
          description: >-
            Share of seasons that are `complete`, as a percentage with one
            decimal
          example: 83.3
    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
    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.