# TheSportsDB Teams, Fixtures & Results (`automation-lab/thesportsdb-teams-events-results`) Actor

Export public TheSportsDB team identities, available next fixtures, recent results and league-season events by team or league ID, with source IDs and scores when exposed.

- **URL**: https://apify.com/automation-lab/thesportsdb-teams-events-results.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Sports
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.52 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TheSportsDB Teams, Fixtures & Results

Export public TheSportsDB teams, available fixtures and scores into an Apify dataset. Enter a team ID to retrieve its identity, next events and last results, or enter a league ID to export teams and optionally available events from a chosen season. This TheSportsDB teams events results workflow is useful for recurring sports-data research, dashboard updates and source-ID reconciliation.

### Who is this for?

Sports analysts can refresh team rosters and fixture tables. Data engineers can join event and team identifiers into existing schedules. Publishers can check upcoming matches and recent scores without copying pages manually.

### Why use this Actor?

One run produces normalized team and event records in the same dataset, with `recordType` separating them. Stable TheSportsDB identifiers make repeated runs comparable. Each record includes a source URL and extraction timestamp. No personal login, proxy or browser is required for the supported public endpoints.

### Getting started

1. Enter **Team ID** or **League ID**, but not both.
2. For league events, supply a **Season**, such as `2024-2025`; without it the run returns league teams only.
3. Set **Maximum records** to cap the combined output.
4. Run the Actor and export the default dataset as JSON, CSV or Excel.

The default team input is `133604` (Arsenal). Another working input is `{"leagueId":"4328","season":"2024-2025","maxItems":40}` for English Premier League teams plus the public API's available events.

### Input parameters

| Field | Meaning |
| --- | --- |
| `teamId` | Numeric TheSportsDB team ID. Produces identity, upcoming event and recent result records. |
| `leagueId` | Numeric TheSportsDB league ID. Produces league team identities. |
| `season` | Optional `YYYY` or `YYYY-YYYY` for league event records. |
| `maxItems` | Combined team and event record cap, 1–1000; default 10. |

A season without league ID, an invalid identifier, or both IDs supplied fails with an error rather than producing misleading rows.

### Extracted data

Each row has `recordType` (`team` or `event`), `sourceId`, `sourceUrl`, `name`, `leagueId`, `league`, `sport`, `season` and `fetchedAt`. Event rows additionally carry `date`, `status`, `homeTeam`, `awayTeam`, `homeTeamId`, `awayTeamId`, `homeScore` and `awayScore` when exposed. Missing values are null, not guessed. Each accepted dataset row triggers the single `item` event. Team and event rows have no separate billing categories.

### Output example

A representative event from the Arsenal team route:

```json
{"recordType":"event","sourceId":"2494022","sourceUrl":"https://www.thesportsdb.com/event/2494022","name":"Arsenal vs Chelsea","date":"2026-09-06","homeTeam":"Arsenal","awayTeam":"Chelsea","homeScore":2,"awayScore":1}
```

The actual row also contains nullable league, sport, season, status, team ID and `fetchedAt` fields. Results vary as the public source changes.

### How much does it cost to export TheSportsDB teams and fixtures?

Pay-per-event billing has a one-time `start` event and one `item` event per accepted dataset row. At the BRONZE spend tier, the start event costs $0.00005 and each accepted item costs $0.0008712. A 1-item run totals $0.0009212 in Actor events; 10 items total $0.008762; 100 items total $0.08717. FREE is $0.0010019/item, SILVER $0.00067954/item, and GOLD/PLATINUM/DIAMOND $0.00052272/item; the one-time start is $0.00005 for each tier. Tiers depend on qualifying Apify Store spend, not how many rows this run returns. Empty results do not incur item charges. Apify platform usage may also apply. Actual billing can vary with delivered items; check the Actor pricing tab before scheduling frequent runs. Any creator revenue or payout estimates are provisional and can be reduced by refunds, fraud, disputes, taxes, corrections and clawbacks.

### Integrations and recurring sports-data workflows

Schedule a team run to periodically compare next-event IDs and most recent score against your previous dataset. Schedule a league/season run to join available event IDs with league team IDs. Use Apify integrations or webhooks to deliver new datasets to a sheet, warehouse or application; the Actor itself does not maintain change state or send alerts.

### API use

Call the Apify run API with your own token:

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~thesportsdb-teams-events-results/run-sync-get-dataset-items?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' -d '{"teamId":"133604","maxItems":10}'
```

JavaScript with `apify-client`:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/thesportsdb-teams-events-results').call({ leagueId: '4328', maxItems: 30 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Python with `apify-client`:

```python
from apify_client import ApifyClient
import os
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/thesportsdb-teams-events-results').call(run_input={'teamId': '133604'})
print(client.dataset(run['defaultDatasetId']).list_items().items)
```

### MCP use

In Claude Code, register the hosted Apify MCP integration:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/thesportsdb-teams-events-results"
```

Claude Desktop, Cursor and VS Code can each use this HTTP MCP server URL in their MCP server configuration. For example, the JSON configuration for Claude Desktop or another compatible editor is:

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/thesportsdb-teams-events-results"}}}
```

Example prompts for MCP usage: “Run the TheSportsDB Actor for team ID 133604, then summarize Arsenal's next fixture and most recent result with event IDs.” “Run it for league ID 4328 and season 2024-2025; export the available team and event rows to a CSV.”

### Data coverage

Team event endpoints expose limited next and last windows. League season queries expose only the public endpoint response; no pagination or completeness guarantee is made.

### Limits and troubleshooting

The free public TheSportsDB JSON API can return a limited subset, especially for season events and league teams; `maxItems` is an upper bound, **not** a request for exhaustive pagination. The ID-based team lookup can return another league's teams; when that happens the Actor falls back to a name-based lookup and only emits rows whose source league ID matches the requested league. Team identities reflect current source membership, not necessarily the historical season's roster. The team route returns only the endpoint's next and last event windows. No historical backfill, all-event coverage, live-score guarantee, or alerting is offered. Event status and score can be missing for future fixtures.

If the output is empty, check the numeric ID and whether the source exposes that team or league. For season events, check the season spelling. Temporary network or upstream errors are retried at most twice; persistent failures propagate as run failures instead of appearing as empty valid datasets.

### Legality and responsible use

Use public source records in accordance with TheSportsDB terms, attribution requirements and applicable law. Confirm rights for redistribution and commercial use. This Actor does not bypass access controls or collect private account data. It is an independent automation, not affiliated with, certified or endorsed by TheSportsDB or Apify.

### Related Actors

For a different sports source and official US college schedules, see [NCAA College Sports Schedules & Scores API](https://apify.com/automation-lab/ncaa-college-sports-data-api). Its NCAA coverage is separate from TheSportsDB identifiers.

### AI and data handling

The Actor does not use AI. It sends numeric identifiers to TheSportsDB public JSON endpoints and receives public team/event records. It does not need a user key or private account, store a cross-run cache, or export personal profiles. Apify stores input, logs and datasets according to the user's Apify account retention settings; delete runs and datasets from Apify Console when no longer needed. No secret or personal input should be submitted.

### Support

For a source outage or unexpected field, open an issue through the Actor's Apify Store support interface with the input and run URL (omit secrets). Compare a failed run with the live TheSportsDB API response to distinguish source changes from parser errors.

### FAQ

**Can I export an entire league season?** The Actor fetches the public season endpoint but cannot guarantee exhaustive records or pagination beyond what that API exposes.

**Why are scores null?** Upcoming matches may not yet have scores; the source may also omit fields.

**Can I monitor changes?** Schedule recurring runs and compare source IDs and values downstream. This Actor does not emit change notifications itself.

**Does a failed source request look like zero results?** No. Invalid response shapes and exhausted transient retries fail the run.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/thesportsdb-teams-events-results/changelog.md

# Actor input Schema

## `teamId` (type: `string`):

Numeric TheSportsDB team ID. Returns the team, next events and last results; do not combine with league ID.

## `leagueId` (type: `string`):

Numeric TheSportsDB league ID. Returns league teams; add season for season events. Do not combine with team ID.

## `season` (type: `string`):

Optional season for league events, e.g. 2024-2025. The public API may return a limited subset.

## `maxItems` (type: `integer`):

Combined maximum of teams and events in the output dataset.

## Actor input object example

```json
{
  "teamId": "133604",
  "maxItems": 10
}
```

# Actor output Schema

## `overview` (type: `string`):

Team and event records with source IDs, schedules and scores when available

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "teamId": "133604"
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/thesportsdb-teams-events-results").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "teamId": "133604" }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/thesportsdb-teams-events-results").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "teamId": "133604"
}' |
apify call automation-lab/thesportsdb-teams-events-results --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/thesportsdb-teams-events-results"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7NCVG01zimu99LC2Y/builds/Q7m6roz7rA4X8J2Ta/openapi.json