> ## Documentation Index
> Fetch the complete documentation index at: https://padelapi.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Discover how to access and use the Padel API for professional padel data. Learn about authentication, coverage, rate limits, and supported tournaments.

> <Icon icon="sparkles" /> Prefer an AI assistant? Connect Claude or ChatGPT via [Padel Analyst](/docs/padel-analyst).

## Authentication

The **Padel API** uses API tokens to authenticate requests. These are provided to you on your [API Tokens](https://padelapi.org/user/api-tokens) management page.

To authenticate, you need to include an `Authorization` header in all of your requests. In this header, you must state that you're using an API token (similar to [HTTP basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)).

For example:

```bash theme={null}
curl -i -X GET \
  'https://padelapi.org/api/seasons' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'
```

Either if the API key isn't valid, or you don't provide an `Authorization` header at all, you'll receive a `401` status code as response

## Tournaments Coverage

To guarantee the highest data quality and consistency, Padel API currently focuses on the following tournament levels.

This ensures comprehensive and timely coverage of draws, schedules, matches, results, and statistics.

Feature availability varies by tournament level. Refer to the tables below for the current availability of Results, Stats, and Live coverage. For guidance on keeping your local data up to date, see the [Data Synchronization](/docs/guides/data-synchronization) guide.

### Padel FIP & Premier Padel

Lower-tier events (such as FIP Rise, FIP Promises, national or exhibition events, and qualifiers) may have incomplete or inconsistent data at the source, so we cannot guarantee the same quality.

![Padel API](https://raw.githubusercontent.com/ferranfg/docs.padelapi.org/refs/heads/master/images/padelapi-padelfip-2.jpeg)

| Level          | Score | Stats | Point by point |
| -------------- | ----- | ----- | -------------- |
| `major`        | ✅     | ✅     | ✅              |
| `p1`           | ✅     | ✅     | ✅              |
| `p2`           | ✅     | ✅     | ✅              |
| `finals`       | ✅     | ✅     | ✅              |
| `fip_platinum` | ✅     | ✅     | ✅              |
| `fip_gold`     | ✅     | ❌     | ❌              |
| `fip_silver`   | ✅     | ❌     | ❌              |
| `fip_other`\*  | ✅     | ❓     | ❓              |

\*Other tournaments may include manually curated individual FIP events of particular relevance, such as the FIP World Cup Pairs.

### World Padel Tour

The World Padel Tour (WPT) was the leading professional circuit until 2023. We provide scores for its main event categories. Stats and point-by-point data are not available at this level.

| Level        | Score | Stats | Point by point |
| ------------ | ----- | ----- | -------------- |
| `wpt_master` | ✅     | ❌     | ❌              |
| `wpt_1000`   | ✅     | ❌     | ❌              |
| `wpt_500`    | ✅     | ❌     | ❌              |
| `wpt_final`  | ✅     | ❌     | ❌              |

### Padel Pro Tour

The Padel Pro Tour (PPT) was the main professional circuit in Spain and the predecessor of the World Padel Tour. We provide scores for its full range of event categories. Stats and point-by-point data are not available at this level.

| Level               | Score | Stats | Point by point |
| ------------------- | ----- | ----- | -------------- |
| `ppt_master`        | ✅     | ❌     | ❌              |
| `ppt_international` | ✅     | ❌     | ❌              |
| `ppt_final`         | ✅     | ❌     | ❌              |
| `ppt_promotional`   | ✅     | ❌     | ❌              |
| `ppt_other`         | ✅     | ❌     | ❌              |

### Historical Coverage

Our historical depth varies by season, and we are continuously expanding it as more data meets our quality standards.

<Note>
  **From 2023 onwards**, we provide **complete draws** for the covered tournament levels — every round, from qualifiers and early rounds through to the final.

  **From 2006 to 2023**, we currently provide **finals only**. We are actively reconstructing the earlier rounds of these events and will add them as they become available.
</Note>

## Rate Limits

The **Padel API** limits the number of requests you can make to protect the service and ensure fair usage for all users.

| Limit               | Free   | Plus & Pro | Business  |
| ------------------- | ------ | ---------- | --------- |
| Requests per minute | 10     | 60         | 500       |
| Requests per day    | 2,000  | 4,000      | 100,000   |
| Requests per month  | 50,000 | 50,000     | 2,000,000 |

When you exceed a rate limit, the API returns a [`429 Too Many Requests`](/docs/error-codes#429-too-many-requests) error. Wait until the limit resets before making additional requests.

The API includes the following headers in responses to help you track your usage:

| Header                  | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed per minute      |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window |

<Tip>
  Use caching strategies and monitor `X-RateLimit-Remaining` to avoid hitting the limit.
</Tip>

You can track your API usage at any time from the [Logs & Quota](https://padelapi.org/explore/resources/logs) page. It shows a detailed breakdown of your recent requests, along with your daily and monthly quota consumption, so you always know how much of your plan you've used and how much remains.

## Pagination

Several endpoints return paginated results.

By default, the **Padel API** only returns the first 15 results for those endpoints. You can use optional query parameters to increase or decrease the number of results.

| Parameter  | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `per_page` | Number of results to return per page (default: 15, min: 1, max: 50) |
| `page`     | Page number to retrieve                                             |

## Status Codes

The **Padel API** uses conventional [HTTP response codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) to indicate whether a request was successful (`2XX` codes) or resulted in an error (`4XX` and `5XX` codes).

See the [Error Codes](/docs/error-codes) page for details on each status code.

## Roadmap & Issues

❇️ View the official [Padel API public roadmap](https://github.com/users/ferranfg/projects/2).

Our product roadmap is where you can learn about what features we're working on, what stage they're in, and when we expect to bring them to you. Have any questions or comments about items on the roadmap? Share your feedback via [Padel API public issues](https://github.com/ferranfg/docs.padelapi.org/issues).