NAV Navbar
shell
  • Introduction
  • User
  • Avatars
  • Leagues
  • Drafts
  • Players
  • Errors
  • 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

    To fetch a user object, use this code:

    # 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>"
    

    You will get a JSON response that looks something like this:

    {
      "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>

    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"
    

    The above command returns JSON structured like this:

    [
      {
        "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>"
    

    The above command returns JSON structured like this:

    {
      "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"
    

    The above command returns JSON structured like this:

    [
      {
        "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"
    

    The above command returns JSON structured like this:

    [
      {
        "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

    Drafts

    Get all drafts for user

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

    The above command returns JSON structured like this:

    [
      {
        "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"
    

    The above command returns JSON structured like this:

    [
      {
        "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>"
    

    The above command returns JSON structured like this:

    {
      "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"
    

    The above command returns JSON structured like this:

    [
      {
        "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 rosters in a league.

    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

    Players

    To fetch a user object, use this code:

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

    You will get a JSON response that looks something like this:

    {
      "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
      },
      ...
    }
    

    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

    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.