Introduction

The Sleeper API is a read-only HTTP API that is free to use and allows access to a user's leagues, drafts, and rosters.

No API Token is necessary, as you cannot modify contents via this API.

Be mindful of the frequency of calls. A general rule is to stay under 1000 API calls per minute, otherwise, you risk being IP-blocked.

User

# With shell, you can just curl the username or user_id
curl "https://api.sleeper.app/v1/user/<username>"
curl "https://api.sleeper.app/v1/user/<user_id>"

{
  "username": "sleeperuser",
  "user_id": "12345678",
  "display_name": "SleeperUser",
  "avatar": "cc12ec49965eb7856f84d71cf85306af"
}

We do not perform authentication as our API is read-only and only contains league information.

Via the user resource, you can GET the user object by either providing the username or user_id of the user.

GET https://api.sleeper.app/v1/user/<username>

GET https://api.sleeper.app/v1/user/<user_id>

Keep in mind that the username of a user can change over time, so if you are storing information, you'll want to hold onto the user_id.

Avatars

Users and leagues have avatar images. There are thumbnail and full-size images for each avatar.

Full size URL

https://sleepercdn.com/avatars/<avatar_id>

Thumbnail URL

https://sleepercdn.com/avatars/thumbs/<avatar_id>

Leagues

Get all leagues for user

curl "https://api.sleeper.app/v1/user/<user_id>/leagues/nfl/2018"

[
  {
    "total_rosters": 12,
    "status": "pre_draft", // can also be "drafting", "in_season", or "complete"
    "sport": "nfl",
    "settings": { settings object },
    "season_type": "regular",
    "season": "2018",
    "scoring_settings": { scoring_settings object },
    "roster_positions": [ roster positions array ],
    "previous_league_id": "198946952535085056",
    "name": "Sleeperbot Friends League",
    "league_id": "289646328504385536",
    "draft_id": "289646328508579840",
    "avatar": "efaefa889ae24046a53265a3c71b8b64"
  },
  {
    "total_rosters": 12,
    "status": "in_season",
    "sport": "nfl",
    "settings": { settings object },
    "season_type": "regular",
    "season": "2018",
    "scoring_settings": { scoring_settings object },
    "roster_positions": [ roster positions array ],
    "previous_league_id": "198946952535085056",
    "name": "Sleeperbot Dynasty",
    "league_id": "289646328504385536",
    "draft_id": "289646328508579840",
    "avatar": "efaefa889ae24046a53265a3c71b8b64"
  },
]

This endpoint retrieves all leagues.

HTTP Request

GET https://api.sleeper.app/v1/user/<user_id>/leagues/<sport>/<season>

URL Parameters

Parameter	Description
user_id	The numerical ID of the user.
sport	We only support "nfl" right now.
season	Season can be 2017, 2018, etc...

Get a specific league

curl "https://api.sleeper.app/v1/league/<league_id>"

{
  "total_rosters": 12,
  "status": "in_season",
  "sport": "nfl",
  "settings": { settings object },
  "season_type": "regular",
  "season": "2018",
  "scoring_settings": { scoring_settings object },
  "roster_positions": [ roster positions array ],
  "previous_league_id": "198946952535085056",
  "name": "Sleeperbot Dynasty",
  "league_id": "289646328504385536",
  "draft_id": "289646328508579840",
  "avatar": "efaefa889ae24046a53265a3c71b8b64"
}

This endpoint retrieves a specific league.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve

Getting rosters in a league

curl "https://api.sleeper.app/v1/league/<league_id>/rosters"

[
  {
    "starters": ["2307", "2257", "4034", "147", "642", "4039", "515", "4149", "DET"],
    "settings": {
      "wins": 5,
      "waiver_position": 7,
      "waiver_budget_used": 0,
      "total_moves": 0,
      "ties": 0,
      "losses": 9,
      "fpts_decimal": 78,
      "fpts_against_decimal": 32,
      "fpts_against": 1670,
      "fpts": 1617
    },
    "roster_id": 1,
    "reserve": [],
    "players": ["1046", "138", "147", "2257", "2307", "2319", "4034", "4039", "4040", "4149", "421", "515", "642", "745", "DET"],
    "owner_id": "188815879448829952",
    "league_id": "206827432160788480"
  },
  ...
]

This endpoint retrieves all rosters in a league.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/rosters

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve rosters from

Getting users in a league

curl "https://api.sleeper.app/v1/league/<league_id>/users"

[
  {
    "user_id": "<user_id>",
    "username": "<username>",
    "display_name": "<display_name>",
    "avatar": "1233456789",
    "metadata": {
      "team_name": "Dezpacito"
    },
    "is_owner": true   // is commissioner (there can be multiple commissioners)
  },
  ...
]

This endpoint retrieves all users in a league.

This also includes each user's display_name, avatar, and their metadata which sometimes includes a nickname they gave their team.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/users

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve rosters from

Getting matchups in a league

curl "https://api.sleeper.app/v1/league/<league_id>/matchups/<week>"

[
  {
    "starters": ["421", "4035", "3242", "2133", "2449", "4531", "2257", "788", "PHI"],
    "roster_id": 1,
    "players": ["1352", "1387", "2118", "2133", "2182", "223", "2319", "2449", "3208", "4035", "421", "4881", "4892", "788", "CLE"],
    "matchup_id": 2,
    "points": 20.0 // total points for team based on league settings
    "custom_points": null // if commissioner overrides points manually
  },
  ...
]

This endpoint retrieves all matchups in a league for a given week. Each object in the list represents one team. The two teams with the same matchup_id match up against each other.

The starters is in an ordered list of player_ids, and players is a list of all player_ids in this matchup.

The bench can be deduced by removing the starters from the players field.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/matchups/<week>

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve matchups from
week	The week these matchups take place

Getting the playoff bracket

curl "https://api.sleeper.app/v1/league/<league_id>/winners_bracket"
curl "https://api.sleeper.app/v1/league/<league_id>/losers_bracket"

[
  {r: 1, m: 1,   t1: 3,    t2: 6,     w: null, l: null},
  {r: 1, m: 2,   t1: 4,    t2: 5,     w: null, l: null},

  {r: 2, m: 3,   t1: 1,    t2: null,  t2_from: {w: 1},  w: null, l: null},
  {r: 2, m: 4,   t1: 2,    t2: null,  t2_from: {w: 2},  w: null, l: null},
  {r: 2, m: 5,   t1: null, t2: null,  t1_from: {l: 1},  t2_from: {l: 2},  w: null, l: null, p: 5},

  {r: 3, m: 6,   t1: null, t2: null,  t1_from: {w: 3},  t2_from: {w: 4},  w: null, l: null, p: 1},
  {r: 3, m: 7,   t1: null, t2: null,  t1_from: {l: 3},  t2_from: {l: 4},  w: null, l: null, p: 3}
]

This endpoint retrieves the playoff bracket for a league for 4, 6, and 8 team playoffs.

Each row represents a matchup between 2 teams.

Field	Type	Description
r	int	The round for this matchup, 1st, 2nd, 3rd round, etc.
m	int	The match `id` of the matchup, unique for all matchups within a bracket.
t1	int	The `roster_id` of a team in this matchup OR `{w: 1}` which means the winner of match id `1`
t2	int	The `roster_id` of the other team in this matchup OR `{l: 1}` which means the loser of match id `1`
w	int	The `roster_id` of the winning team, if the match has been played.
l	int	The `roster_id` of the losing team, if the match has been played.
t1_from	object	Where t1 comes from, either winner or loser of the match `id`, necessary to show bracket progression.
t2_from	object	Where t2 comes from, either winner or loser of the match `id`, necessary to show bracket progression.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/winners_bracket

GET https://api.sleeper.app/v1/league/<league_id>/loses_bracket

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve matchups from

Get transactions

curl "https://api.sleeper.app/v1/league/<league_id>/transactions/<round>"

[
  {
    "type": "trade",
    "transaction_id": "434852362033561600",
    "status_updated": 1558039402803,
    "status": "complete",
    "settings": null,     // trades do not use this field
    "roster_ids": [2, 1], // roster_ids involved in this transaction
    "metadata": null,
    "leg": 1,         // in football, this is the week
    "drops": null,
    "draft_picks": [  // picks that were traded
      {
        "season": "2019",// the season this draft pick belongs to
        "round": 5,      // which round this draft pick is
        "roster_id": 1,  // original owner's roster_id
        "previous_owner_id": 1,  // previous owner's roster id (in this trade)
        "owner_id": 2,   // the new owner of this pick after the trade
      },
      {
        "season": "2019",
        "round": 3,
        "roster_id": 2,
        "previous_owner_id": 2,
        "owner_id": 1,
      }
    ],
    "creator": "160000000000000000",  // user id who initiated the transaction
    "created": 1558039391576,
    "consenter_ids": [2, 1], // roster_ids of the people who agreed to this transaction
    "adds": null
    "waiver_budget": [   // roster_id 2 sends 55 FAAB dollars to roster_id 3
      {
        "sender": 2,
        "receiver": 3,
        "amount": 55
      }
    ],
  },
  {
    "type": "free_agent",  // could be waiver or trade as well
    "transaction_id": "434890120798142464",
    "status_updated": 1558048393967,
    "status": "complete",
    "settings": null,   // could be {'waiver_bid': 44} if it's FAAB waivers
    "roster_ids": [1],  // roster_ids involved in this transaction
    "metadata": null,   // can contain notes in waivers like why it didn't go through
    "leg": 1,
    "drops": {
      "1736": 1         // player id 1736 dropped from roster_id 1
    },
    "draft_picks": [],
    "creator": "160000000000000000",
    "created": 1558048393967,
    "consenter_ids": [1], // the roster_ids who agreed to this transaction
    "adds": {
      "2315": 1   // player id 2315 added to roster_id 1
      ...
    },
    "waiver_budget": []  // this used for trades only involving FAAB
  },
  ...
]

This endpoint retrieves all free agent transactions, waivers and trades.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/transactions/<round>

URL Parameters

Parameter	Description
league_id	The ID of the draft to retrieve picks for
round	The week you want to pull from

Get traded picks

curl "https://api.sleeper.app/v1/league/<league_id>/traded_picks"

[
  {
    "season": "2019",        // which season the pick is for
    "round": 5,              // which round the pick is
    "roster_id": 1,          // roster_id of ORIGINAL owner
    "previous_owner_id": 1,  // roster_id of the previous owner
    "owner_id": 2,           // roster_id of current owner
  },
  {
    "season": "2020",        // which season the pick is for
    "round": 3,              // which round the pick is
    "roster_id": 2,          // roster_id of original owner
    "previous_owner_id": 2,  // roster_id of previous owner
    "owner_id": 1,           // roster_id of current owner
  },
  ...
]

This endpoint retrieves all traded picks in a league, including future picks.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/traded_picks

URL Parameters

Parameter	Description
league_id	The ID of the league to retrieve traded picks for

Get NFL state

curl "https://api.sleeper.app/v1/state/nfl"

{
  "week": 2, // week
  "season_type": "regular", // pre, post, regular
  "season_start_date": "2020-09-10", // regular season start
  "season": "2020", // current season
  "previous_season": "2019",
  "leg": 2, // week of regular season
  "league_season": "2021", // active season for leagues
  "league_create_season": "2021", // flips in December
  "display_week": 3 // Which week to display in UI, can be different than week
}

This endpoint returns information about the current state for any sport.

HTTP Request

GET https://api.sleeper.app/v1/state/<sport>

URL Parameters

Parameter	Description
sport	nfl, nba, lcs, etc...

Drafts

Get all drafts for user

curl "https://api.sleeper.app/v1/user/<user_id>/drafts/nfl/2018"

[
  {
    "type": "snake",
    "status": "complete",
    "start_time": 1515700800000,
    "sport": "nfl",
    "settings": {
      "teams": 6,
      "slots_wr": 2,
      "slots_te": 1,
      "slots_rb": 2,
      "slots_qb": 1,
      "slots_k": 1,
      "slots_flex": 2,
      "slots_def": 1,
      "slots_bn": 5,
      "rounds": 15,
      "pick_timer": 120
    },
    "season_type": "regular",
    "season": "2017",
    "metadata": {
      "scoring_type": "ppr",
      "name": "My Dynasty",
      "description": ""
    },
    "league_id": "257270637750382592",
    "last_picked": 1515700871182,
    "last_message_time": 1515700942674,
    "last_message_id": "257272036450111488",
    "draft_order": null,
    "draft_id": "257270643320426496",
    "creators": null,
    "created": 1515700610526
  },
  ...
]

This endpoint retrieves all drafts by a user.

HTTP Request

GET https://api.sleeper.app/v1/user/<user_id>/drafts/<sport>/<season>

URL Parameters

Parameter	Description
user_id	The numerical ID of the user.
sport	We only support "nfl" right now.
season	Season can be 2017, 2018, etc...

Get all drafts for a league

curl "https://api.sleeper.app/v1/league/<league_id>/drafts"

[
  {
    "type": "snake",
    "status": "complete",
    "start_time": 1515700800000,
    "sport": "nfl",
    "settings": {
      "teams": 6,
      "slots_wr": 2,
      "slots_te": 1,
      "slots_rb": 2,
      "slots_qb": 1,
      "slots_k": 1,
      "slots_flex": 2,
      "slots_def": 1,
      "slots_bn": 5,
      "rounds": 15,
      "pick_timer": 120
    },
    "season_type": "regular",
    "season": "2017",
    "metadata": {
      "scoring_type": "ppr",
      "name": "My Dynasty",
      "description": ""
    },
    "league_id": "257270637750382592",
    "last_picked": 1515700871182,
    "last_message_time": 1515700942674,
    "last_message_id": "257272036450111488",
    "draft_order": null,
    "draft_id": "257270643320426496",
    "creators": null,
    "created": 1515700610526
  },
  ...
]

This endpoint retrieves all drafts for a league. Keep in mind that a league can have multiple drafts, especially dynasty leagues.

Drafts are sorted by most recent to earliest. Most leagues should only have one draft.

HTTP Request

GET https://api.sleeper.app/v1/league/<league_id>/drafts

URL Parameters

Parameter	Description
league_id	The ID of the league for which you are trying to retrieve drafts.

Get a specific draft

curl "https://api.sleeper.app/v1/draft/<draft_id>"

{
  "type": "snake",
  "status": "complete",
  "start_time": 1515700800000,
  "sport": "nfl",
  "settings": {
    "teams": 6,
    "slots_wr": 2,
    "slots_te": 1,
    "slots_rb": 2,
    "slots_qb": 1,
    "slots_k": 1,
    "slots_flex": 2,
    "slots_def": 1,
    "slots_bn": 5,
    "rounds": 15,
    "pick_timer": 120
  },
  "season_type": "regular",
  "season": "2017",
  "metadata": {
    "scoring_type": "ppr",
    "name": "My Dynasty",
    "description": ""
  },
  "league_id": "257270637750382592",
  "last_picked": 1515700871182,
  "last_message_time": 1515700942674,
  "last_message_id": "257272036450111488",

  // this is the user_id to draft slot mapping
  "draft_order": {
    "12345678": 1,
    "23434332": 2,
    ...
  },

  // this is the draft slot to roster_id mapping
  // leagues have rosters, which have roster_ids
  // this means draft slot 1 (column 1) will go to roster 10, slot 2 will go to roster_id 3, etc
  "slot_to_roster_id": {
    "1": 10,
    "2": 3,
    "3": 5
  },

  "draft_id": "257270643320426496",
  "creators": null,
  "created": 1515700610526
}

This endpoint retrieves a specific draft.

HTTP Request

GET https://api.sleeper.app/v1/draft/<draft_id>

URL Parameters

Parameter	Description
draft_id	The ID of the draft to retrieve

Get all picks in a draft

curl "https://api.sleeper.app/v1/draft/<draft_id>/picks"

[
  {
    "player_id": "2391",
    "picked_by": "234343434", // user_id this pick will go to (not all leagues have users in every slot, this can be "")
    "roster_id": "1", // roster_id this pick will go to
    "round": 5,
    "draft_slot": 5, // which column this is on the draftboard
    "pick_no": 1,
    "metadata": {
      "team": "ARI",
      "status": "Injured Reserve",
      "sport": "nfl",
      "position": "RB",
      "player_id": "2391",
      "number": "31",
      "news_updated": "1513007102037",
      "last_name": "Johnson",
      "injury_status": "Out",
      "first_name": "David"
    },
    "is_keeper": null,
    "draft_id": "257270643320426496"
  },
  {
    "player_id": "1408",
    "picked_by": "234343434", // user_id this pick will go to (not all leagues have users in every slot, this can be "")
    "roster_id": "1", // roster_id this pick will go to
    "round": 5,
    "draft_slot": 6,
    "pick_no": 2,
    "metadata": {
      "team": "PIT",
      "status": "Active",
      "sport": "nfl",
      "position": "RB",
      "player_id": "1408",
      "number": "26",
      "news_updated": "1515698101257",
      "last_name": "Bell",
      "injury_status": "",
      "first_name": "Le'Veon"
    },
    "is_keeper": null,
    "draft_id": "257270643320426496"
  },
  {
    "player_id": "536",
    "picked_by": "667279356739584",
    "pick_no": 3,
    "metadata": {
      "team": "PIT",
      "status": "Active",
      "sport": "nfl",
      "position": "WR",
      "player_id": "536",
      "number": "84",
      "news_updated": "1515673801292",
      "last_name": "Brown",
      "injury_status": "Probable",
      "first_name": "Antonio"
    },
    "is_keeper": null,
    "draft_id": "257270643320426496"
  },
  ...
]

This endpoint retrieves all picks in a draft.

HTTP Request

GET https://api.sleeper.app/v1/draft/<draft_id>/picks

URL Parameters

Parameter	Description
draft_id	The ID of the draft to retrieve picks for

Get traded picks in a draft

curl "https://api.sleeper.app/v1/draft/<draft_id>/traded_picks"

[
  {
    "season": "2019",
    "round": 5,              // which round the pick is
    "roster_id": 1,          // roster_id of ORIGINAL owner
    "previous_owner_id": 1,  // roster_id of the previous owner
    "owner_id": 2,           // roster_id of current owner
  },
  {
    "season": "2019",
    "round": 3,              // which round the pick is
    "roster_id": 2,          // roster_id of original owner
    "previous_owner_id": 2,  // roster_id of previous owner
    "owner_id": 1,           // roster_id of current owner
  },
  ...
]

This endpoint retrieves all traded picks in a draft.

HTTP Request

GET https://api.sleeper.app/v1/draft/<draft_id>/traded_picks

URL Parameters

Parameter	Description
draft_id	The ID of the draft to retrieve picks for

Players

Fetch all players

curl "https://api.sleeper.app/v1/players/nfl"

{
  "3086": {
    "hashtag": "#TomBrady-NFL-NE-12",
    "depth_chart_position": 1,
    "status": "Active",
    "sport": "nfl",
    "fantasy_positions": ["QB"],
    "number": 12,
    "search_last_name": "brady",
    "injury_start_date": null,
    "weight": "220",
    "position": "QB",
    "practice_participation": null,
    "sportradar_id": "",
    "team": "NE",
    "last_name": "Brady",
    "college": "Michigan",
    "fantasy_data_id":17836,
    "injury_status":null,
    "player_id":"3086",
    "height": "6'4\"",
    "search_full_name": "tombrady",
    "age": 40,
    "stats_id": "",
    "birth_country": "United States",
    "espn_id": "",
    "search_rank": 24,
    "first_name": "Tom",
    "depth_chart_order": 1,
    "years_exp": 14,
    "rotowire_id": null,
    "rotoworld_id": 8356,
    "search_first_name": "tom",
    "yahoo_id": null
  },
  ...
}

Please use this call sparingly, as it is intended only to be used once per day at most to keep your player IDs updated. The average size of this query is 5MB.

Since rosters and draft picks contain Player IDs which look like "1042", "2403", "CAR", etc, you will need to know what those IDs map to. The /players call provides you the map necessary to look up any player.

You should save this information on your own servers as this is not intended to be called every time you need to look up players due to the filesize being close to 5MB in size. You do not need to call this endpoint more than once per day.

GET https://api.sleeper.app/v1/players/nfl

curl "https://api.sleeper.app/v1/players/nfl/trending/add"

[
  {
    "player_id": "1111", // the player_id
    "count": 45         // number or adds
  },
  ...
]

<iframe src="https://sleeper.app/embed/players/nfl/trending/add?lookback_hours=24&limit=25" width="350" height="500" allowtransparency="true" frameborder="0"></iframe>

You can use this endpoint to get a list of trending players based on adds or drops in the past 24 hours.

GET https://api.sleeper.app/v1/players/<sport>/trending/<type>?lookback_hours=<hours>&limit=<int>

URL Parameters

Parameter	Description
sport	The sport, such as `nfl`
type	Either `add` or `drop`
lookback_hours	Number of hours to look back (default is 24) - optional
limit	Number of results you want, (default is 25) - optional

Errors

The Sleeper API uses the following error codes:

Code	Meaning
400	Bad Request -- Your request is invalid.
404	Not Found -- The specified kitten could not be found.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Introduction

User

Avatars

Leagues

Get all leagues for user

HTTP Request

URL Parameters

Get a specific league

HTTP Request

URL Parameters

Getting rosters in a league

HTTP Request

URL Parameters

Getting users in a league

HTTP Request

URL Parameters

Getting matchups in a league

HTTP Request

URL Parameters

Getting the playoff bracket

HTTP Request

URL Parameters

Get transactions

HTTP Request

URL Parameters

Get traded picks

HTTP Request

URL Parameters

Get NFL state

HTTP Request

URL Parameters

Drafts

Get all drafts for user

HTTP Request

URL Parameters

Get all drafts for a league

HTTP Request

URL Parameters

Get a specific draft

HTTP Request

URL Parameters

Get all picks in a draft

HTTP Request

URL Parameters

Get traded picks in a draft

HTTP Request

URL Parameters

Players

Fetch all players

Trending Players

URL Parameters

Errors