# Sleeper NFL Fantasy Data API (`automation-lab/sleeper-nfl-fantasy-api`) Actor

Export public Sleeper NFL leagues, users, rosters, weekly matchups, drafts, transactions, and referenced players by username or league ID.

- **URL**: https://apify.com/automation-lab/sleeper-nfl-fantasy-api.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Sports
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.08 / 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Sleeper NFL Fantasy Data API

Export public Sleeper NFL fantasy data by username or league ID.

The Actor combines Sleeper's public league endpoints into one normalized dataset for recurring fantasy analysis.
It returns league settings, public members, rosters, weekly matchups, drafts, draft picks, transactions, and referenced player profiles.
No Sleeper login, cookies, browser, or proxy is required.

### What can you do with this Actor?

- Resolve a public Sleeper username and discover that user's NFL leagues for a season.
- Export one or more known leagues without first looking up a username.
- Join league members to rosters for ownership analysis.
- Compare weekly matchup scores and starting lineups.
- Review waivers, free-agent moves, trades, and other weekly transactions.
- Export draft metadata and every pick from each league draft.
- Enrich roster player IDs with profiles from Sleeper's NFL player catalog.
- Schedule the same input to feed dashboards, spreadsheets, databases, and fantasy tools.

### Who is it for?

**Fantasy analysts** can build matchup reports and transaction summaries.

**League commissioners** can archive public league settings, members, rosters, and drafts.

**App developers** can use a stable Apify dataset instead of orchestrating many Sleeper endpoints.

**Data teams** can schedule repeat exports and compare dataset snapshots downstream.

### Why use it instead of calling one endpoint?

A league analysis usually needs several related resources.
This Actor resolves usernames, discovers season leagues, follows league-to-draft relationships, and optionally maps roster player IDs to profiles.
It provides:

- one validated input contract;
- bounded retries for transient Sleeper API errors;
- a global output limit;
- normalized join keys on every row;
- the complete source object in `data`;
- Apify scheduling, webhooks, integrations, API access, and MCP access.

### Data you can extract

| Record type | What it contains | Useful join fields |
| --- | --- | --- |
| `league` | League name, season, status, scoring and roster settings | `leagueId`, `season` |
| `user` | Public username, display name, avatar, league metadata | `userId`, `leagueId` |
| `roster` | Owner, players, starters, reserve/taxi lists, settings | `rosterId`, `userId`, `leagueId` |
| `matchup` | Weekly points, starters, players, matchup pairing | `matchupId`, `rosterId`, `week` |
| `draft` | Draft type, status, settings, order, start time | `draftId`, `leagueId` |
| `draft_pick` | Pick number, player, roster, round, pick metadata | `draftId`, `playerId`, `rosterId` |
| `transaction` | Waivers, trades, adds, drops, roster participants | `transactionId`, `leagueId`, `week` |
| `player` | Referenced NFL player profile and team/position data | `playerId` |

Every item includes `recordType`, `sourceUrl`, and `scrapedAt`.
Fields that do not apply to an entity are `null`.
The `data` object preserves all public fields returned by Sleeper so advanced users are not limited to the overview columns.

### Getting started

1. Open the Actor input page.
2. Enter a public Sleeper username, one or more league IDs, or both.
3. Set `season` when using username-based league discovery.
4. Select the record types you need.
5. Add NFL week numbers for matchups and transactions.
6. Set `maxItems` to cap total dataset records.
7. Click **Start**.
8. Open the **Results** dataset or export it as JSON, CSV, Excel, XML, or RSS.

The prefilled league ID comes from Sleeper's public API documentation and is suitable for a small evaluation run.

### Input parameters

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `username` | string | none | Public Sleeper username to resolve |
| `leagueIds` | string\[] | none | Public Sleeper NFL league IDs |
| `season` | string | current Sleeper season | Season for username league discovery |
| `weeks` | string\[] | `["1"]` | Weeks 1–18 used for matchups and transactions |
| `entityTypes` | string\[] | league, user, roster, matchup, draft, draft pick, transaction | Records to export |
| `maxItems` | integer | `500` | Maximum total rows, from 1 to 10,000 |

At least one of `username` or `leagueIds` is required.
League IDs are strings because Sleeper identifiers are larger than safe integers in some languages.

### Input example: league rosters

```json
{
  "leagueIds": ["289646328504385536"],
  "entityTypes": ["league", "user", "roster"],
  "maxItems": 50
}
```

### Input example: weekly analysis

```json
{
  "leagueIds": ["289646328504385536"],
  "weeks": ["1"],
  "entityTypes": [
    "roster",
    "matchup",
    "transaction",
    "draft",
    "draft_pick",
    "player"
  ],
  "maxItems": 500
}
```

### Output example

```json
{
  "recordType": "roster",
  "sourceUrl": "https://api.sleeper.app/v1/league/289646328504385536/rosters",
  "leagueId": "289646328504385536",
  "season": "2018",
  "week": null,
  "userId": "188815879448829952",
  "username": null,
  "displayName": null,
  "rosterId": 1,
  "matchupId": null,
  "draftId": null,
  "transactionId": null,
  "playerId": null,
  "name": null,
  "status": null,
  "data": {
    "roster_id": 1,
    "owner_id": "188815879448829952",
    "players": ["4046", "4017"]
  },
  "scrapedAt": "2026-09-05T06:00:00.000Z"
}
```

The example is shortened.
Actual `data` objects contain the complete response supplied by Sleeper.

### Record ordering and limits

Rows are emitted in deterministic workflow order:

1. resolved username and discovered leagues;
2. explicit league details;
3. league users;
4. rosters;
5. matchups by requested week;
6. transactions by requested week;
7. drafts and picks;
8. referenced player profiles.

`maxItems` applies across all record types and leagues.
When the limit is reached, later entity types are not fetched or emitted.
Choose only the entity types needed for predictable exports.

### Referenced player enrichment

Selecting `player` first collects player IDs from the requested league rosters.
The Actor then downloads Sleeper's NFL player catalog once and emits only profiles referenced by those rosters.
It does not dump the entire catalog.

This is the heaviest mode because the upstream player catalog is large.
Use a practical `maxItems` and request `player` only when profile enrichment is needed.

### Weekly matchups and transactions

Sleeper exposes matchups and transactions by NFL week.
Supply one or more values from `1` through `18`.
The Actor applies the same weeks to both entity types.

Future weeks or inactive historical weeks can legitimately return no rows.
That does not prevent league, member, roster, or draft records from being exported.

### How much does it cost to export Sleeper NFL fantasy records?

Pricing uses pay per event:

- one **Start** event per run;
- one **Sleeper record** event for each useful dataset item saved.

The run start costs **$0.002**. The per-record tiers are **$0.00207 FREE**, **$0.0018 BRONZE**, **$0.001404 SILVER**, and **$0.00108 GOLD / PLATINUM / DIAMOND**.
The active price is also shown on the Actor pricing tab before a run starts.
There is no separate fee for users, rosters, matchups, drafts, transactions, or players; all use the same record event.

For a cost estimate, multiply the applicable record price by the requested output count and add the start event.
The Actor never charges a record event for rejected, duplicate, or failed records.
Platform usage treatment follows the pricing details shown in your Apify account.

### Scheduling recurring fantasy analysis

Create an Apify Schedule with the same league IDs and weeks.
After each run, send the dataset to:

- Google Sheets for commissioner reports;
- a webhook for a fantasy application;
- Make or Zapier for no-code workflows;
- BigQuery, PostgreSQL, or another warehouse;
- your own service through the dataset API.

For week-by-week monitoring, update the `weeks` input as the NFL season progresses or maintain separate scheduled Tasks per week.
Use a downstream key such as `recordType + leagueId + week + rosterId` to compare snapshots.

### cURL API example

Set `APIFY_TOKEN` in your environment, then run:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~sleeper-nfl-fantasy-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "leagueIds": ["289646328504385536"],
    "weeks": ["1"],
    "entityTypes": ["league", "roster", "matchup"],
    "maxItems": 100
  }'
```

Poll the returned run or use the synchronous endpoint when the expected result is small.
Never commit your Apify token to source control.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/sleeper-nfl-fantasy-api').call({
  leagueIds: ['289646328504385536'],
  weeks: ['1'],
  entityTypes: ['roster', 'matchup', 'transaction'],
  maxItems: 200,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/sleeper-nfl-fantasy-api").call(run_input={
    "leagueIds": ["289646328504385536"],
    "entityTypes": ["league", "user", "roster"],
    "maxItems": 50,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI agents

#### Claude Code

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com/?tools=automation-lab/sleeper-nfl-fantasy-api"
```

#### Claude Desktop, Cursor, and VS Code

Desktop and editor clients can use this equivalent JSON configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=automation-lab/sleeper-nfl-fantasy-api"
    }
  }
}
```

Example prompts:

- “Export users and rosters for Sleeper league 289646328504385536.”
- “Get week 1 matchups and transactions and summarize roster changes.”
- “Fetch draft picks and referenced player profiles for this public league.”

### Reliability and retries

The Actor calls Sleeper's public JSON API directly.
Each request has a 20-second timeout.
Transient network errors, HTTP 429 responses, and server errors are retried up to three times with bounded backoff.
Stable client errors and missing league IDs fail immediately with a non-zero run status.

No proxy fallback is enabled because the public API works anonymously.
If Sleeper changes or rate-limits an endpoint, inspect the run log rather than treating an empty response as successful extraction.

### Limitations

- Only public Sleeper data is available.
- The workflow is limited to NFL leagues.
- Username league discovery is season-specific.
- Sleeper can remove old leagues or change its public response fields.
- Weekly endpoints may be empty for weeks without activity.
- Player enrichment requires downloading the large NFL player catalog.
- The Actor does not calculate standings, projections, optimal lineups, or win probabilities.
- It does not monitor continuously inside one run; use Apify Schedules for recurring exports.

### Legality and responsible use

Sleeper exposes these endpoints publicly, but public availability does not remove your responsibilities.
Use the data only for legitimate fantasy analysis, league administration, research, or applications you are authorized to operate.
Do not use public usernames or metadata for harassment, unwanted profiling, or spam.
Follow Sleeper's terms, Apify's policies, and applicable privacy and database laws.
Store exported data only as long as your purpose requires.

### Troubleshooting

**The run says a league was not found.**

Check that the league ID contains digits only and that the league still exists publicly.
Copy the ID from a Sleeper league URL rather than a team or user URL.

**Username lookup returns a user but no leagues.**

Set the season that contains the user's league.
A user can exist without participating in an NFL league in the chosen season.

**There are no transaction or matchup rows.**

Check the requested weeks and season context.
A valid week with no activity can return an empty array.

**The output stopped before player records.**

Increase `maxItems` or deselect earlier entity types.
The global cap may be reached before player enrichment begins.

**The run was rate-limited.**

The Actor retries bounded transient failures automatically.
If retries are exhausted, wait before starting another run or reduce the number of leagues and weeks per run.

### FAQ

#### Does this Actor require my Sleeper password?

No.
It uses public anonymous Sleeper API endpoints and never accepts account credentials.

#### Can I export several leagues in one run?

Yes.
Add multiple IDs to `leagueIds`; `maxItems` remains a global cap.

#### Can I combine username and league ID inputs?

Yes.
The Actor deduplicates discovered and explicitly supplied league IDs.

#### Are records flattened completely?

Important join and display fields are normalized at the top level.
The complete source object remains in `data` so no public source fields are intentionally discarded.

#### Can I fetch only roster players?

Select `roster` and `player`.
Player profiles are limited to IDs referenced by fetched rosters.

#### How fresh is the data?

Each run fetches the current response from Sleeper.
`scrapedAt` records when each dataset item was created.

### Related Automation Lab Actors

For player rankings and projections outside Sleeper league state, use [FantasyPros NFL Projections & Rankings](https://apify.com/automation-lab/fantasypros-nfl-projections-rankings).

That Actor is a complementary dataset.
It does not replace Sleeper league users, rosters, matchups, drafts, or transactions.

# Actor input Schema

## `username` (type: `string`):

Public Sleeper username to resolve. The Actor exports the user and discovers that user's NFL leagues for the selected season.

## `leagueIds` (type: `array`):

One or more public Sleeper league IDs. Use this for precise league exports; it can be combined with username discovery.

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

Season used when discovering leagues by username. Defaults to Sleeper's current league season.

## `weeks` (type: `array`):

Weeks to export for matchups and transactions.

## `entityTypes` (type: `array`):

Choose the records to export. Players means player profiles referenced by exported rosters; it does not dump the entire NFL player catalog.

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

Maximum total dataset records across all requested leagues and entity types.

## Actor input object example

```json
{
  "leagueIds": [
    "289646328504385536"
  ],
  "season": "2025",
  "weeks": [
    "1"
  ],
  "entityTypes": [
    "league",
    "user",
    "roster",
    "matchup"
  ],
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Sleeper leagues, users, rosters, matchups, drafts, transactions, and players.

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

Table view of the most useful normalized fields.

# 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 = {
    "leagueIds": [
        "289646328504385536"
    ],
    "season": "2025",
    "weeks": [
        "1"
    ],
    "entityTypes": [
        "league",
        "user",
        "roster",
        "matchup"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/sleeper-nfl-fantasy-api").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 = {
    "leagueIds": ["289646328504385536"],
    "season": "2025",
    "weeks": ["1"],
    "entityTypes": [
        "league",
        "user",
        "roster",
        "matchup",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/sleeper-nfl-fantasy-api").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 '{
  "leagueIds": [
    "289646328504385536"
  ],
  "season": "2025",
  "weeks": [
    "1"
  ],
  "entityTypes": [
    "league",
    "user",
    "roster",
    "matchup"
  ],
  "maxItems": 20
}' |
apify call automation-lab/sleeper-nfl-fantasy-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/sleeper-nfl-fantasy-api"
        }
    }
}

```

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/ktRhfW7fliR7YMP3c/builds/Sxws0HHfryISbI22E/openapi.json