> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/make-your-first-request.md). # Make your first request This tutorial walks through your first live call to the Motorsport API, then shows how adding an include changes the response. 10 minutes Skill level: Beginner Prerequisites: Authentication ### Before you start Make sure you have an API token. See [Authentication](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/authentication) if you do not have one yet. ### Request 1: a basic request Every request starts with the base URL for the entity you want, plus your token. Let's request all fixtures in your subscription: ```http https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN ``` Paste this into your browser, Postman, or a terminal with `curl`, substituting your real token. A basic response looks like this: ```json { "data": [ { "id": 123456, "name": "Bahrain Grand Prix 2024", "starting_at": "2024-03-02 15:00:00", "state_id": 1, "stage_id": 5001, "venue_id": 12 } ], "subscription": [ { "meta": {}, "plans": [] } ], "rate_limit": { "resets_in_seconds": 3421, "remaining": 2997, "requested_entity": "Fixture" } } ``` Notice the `rate_limit` object. The default plan provides 3,000 API calls per entity per hour, and the limit resets one hour after your first request to that entity. This is a basic response: just the core fields. No driver lineups, no results, no venue details. ### Request 2: add an include To get more than the basic fields, add `&include=`. Let's enrich the same fixture with its state: ```http https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN&include=state ``` Each entity supports a different set of includes. You can find the available includes for each endpoint on its page under [Endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints). ### Request 3: multiple includes You can chain includes with a semicolon to enrich the response further in a single call: ```http https://api.sportmonks.com/v3/motorsport/fixtures ?api_token=YOUR_TOKEN&include=state;lineups;results ``` This single request now returns the fixture, its current state, the driver lineup, and the session results, instead of three separate calls. ### Code examples {% tabs %} {% tab title="JavaScript" %} ```javascript const API_TOKEN = 'YOUR_TOKEN'; async function getFixtures() { const url = `https://api.sportmonks.com/v3/motorsport/fixtures?api_token=${API_TOKEN}&include=state`; try { const response = await fetch(url); const data = await response.json(); return data.data; } catch (error) { console.error('Error fetching fixtures:', error); } } ``` {% endtab %} {% tab title="Python" %} ```python import requests API_TOKEN = "YOUR_TOKEN" def get_fixtures(): url = "https://api.sportmonks.com/v3/motorsport/fixtures" params = { "api_token": API_TOKEN, "include": "state", } try: response = requests.get(url, params=params) response.raise_for_status() data = response.json() return data.get("data", []) except requests.RequestException as error: print("Error fetching fixtures:", error) return None ``` {% endtab %} {% tab title="PHP" %} ```php 'https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN&include=state', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ### Common pitfalls **Forgetting the semicolon between includes.** Includes are separated with `;`, not `,`. A comma-separated include list silently fails or returns unexpected results depending on the endpoint. **Assuming every entity supports every include.** Not all includes are available on every endpoint. Check the specific endpoint's documentation before assuming an include exists. **Treating an empty `data` array as an error.** If your subscription does not include a particular league or season, or there are simply no fixtures matching your query, you will get a `200` response with an empty `data` array. This is expected behaviour, not a failure. ### FAQ **Why is my response missing fields I expected?** The default response only includes core fields. Add the relevant include, or check whether the field is gated behind a `select=` restriction. See [Filter and select fields](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields). **Can I test requests without writing code?** Yes. Paste any request URL directly into a browser address bar, or use a tool like Postman. ### Related * [Authentication](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/authentication) * [Enrich your response](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response) * [Endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints) --- # 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://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/make-your-first-request.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.