# leagues

Read the fantasy leagues a person has connected.

| Method | Path | Title | Access | Price | MCP tool |
| --- | --- | --- | --- | --- | --- |
| GET | [`/v1/me/league-history`](#get-my-league-history) | Get your league history | `read:league` | 0 | `get_my_league_history` |
| GET | [`/v1/leagues`](#list-leagues) | List connected leagues | `read:league` | 1 | none |
| GET | [`/v1/leagues/{league_id}`](#get-league) | Get a connected league | `read:league` | 3 | `get_league` |
| GET | [`/v1/leagues/{league_id}/sync`](#get-league-sync) | Get how fresh a league is | `read:league` | 0 | `get_league_sync` |
| POST | [`/v1/leagues/{league_id}/sync`](#refresh-my-league) | Read a league again now | `read:league` | 0 | `refresh_my_league` |
| GET | [`/v1/leagues/{league_id}/teams`](#get-league-team) | Get a team in your league | `read:league` | 0 | `get_league_team` |
| GET | [`/v1/leagues/{league_id}/waivers`](#get-league-waivers) | Get your league's waiver wire | `read:league` | 0 | `get_league_waivers` |
| GET | [`/v1/leagues/{league_id}/activity`](#get-league-activity) | Get your league's activity | `read:league` | 0 | `get_league_activity` |
| GET | [`/v1/leagues/{league_id}/odds`](#get-league-odds) | Get a league's playoff odds | `read:league` | 0 | `get_league_odds` |
| GET | [`/v1/leagues/{league_id}/analysis`](#analyze-league) | Analyze a league | `read:league` | 0 | `analyze_league` |
| GET | [`/v1/me/league-actions`](#list-league-actions) | List your league moves | `read:league` | 0 | `get_my_league_actions` |
| POST | [`/v1/me/league-actions`](#propose-league-action) | Propose a league move | `write:leagues` | 0 | none |
| POST | [`/v1/me/league-actions/batch`](#propose-league-actions) | Propose a move in several leagues | `write:leagues` | 0 | none |
| GET | [`/v1/me/league-actions/{action_id}`](#get-league-action) | Get a league move | `read:league` | 0 | none |
| POST | [`/v1/me/league-actions/{action_id}/confirm`](#confirm-league-action) | Confirm a league move | `write:leagues` | 0 | `confirm_league_action` |
| POST | [`/v1/me/league-actions/{action_id}/cancel`](#cancel-league-action) | Cancel a league move | `write:leagues` | 0 | none |
| POST | [`/v1/me/league-actions/{action_id}/undo`](#undo-league-action) | Undo a league move | `write:leagues` | 0 | none |
| GET | [`/v1/me/leagues/needs`](#get-my-league-needs) | Get what needs fixing in your lineups | `read:league` | 0 | `get_my_league_needs` |
| POST | [`/v1/me/leagues/fixes`](#fix-my-lineups) | Fix your lineups | `write:leagues` | 0 | `fix_my_lineups` |
| GET | [`/v1/me/leagues/week`](#get-my-league-week) | Get your week plan | `read:league` | 0 | `get_my_league_week` |
| PUT | [`/v1/me/leagues/{league_id}/lineup`](#set-lineup) | Set your lineup | `write:leagues` | 0 | `set_my_lineup` |
| POST | [`/v1/me/leagues/{league_id}/claims`](#claim-player) | Claim a player | `write:leagues` | 0 | `claim_player` |
| PATCH | [`/v1/me/leagues/{league_id}/claims`](#update-claims) | Change your claims | `write:leagues` | 0 | `update_my_claims` |
| POST | [`/v1/me/leagues/{league_id}/drops`](#drop-player) | Drop a player | `write:leagues` | 0 | `drop_player` |
| POST | [`/v1/me/leagues/{league_id}/trades`](#propose-trade) | Offer a trade | `write:leagues` | 0 | `propose_trade` |
| POST | [`/v1/me/leagues/{league_id}/trades/{trade_id}/respond`](#respond-to-trade) | Answer a trade offer | `write:leagues` | 0 | `respond_to_trade` |
| PUT | [`/v1/me/leagues/{league_id}/keepers`](#set-keepers) | Name your keepers | `write:leagues` | 0 | `set_my_keepers` |
| PUT | [`/v1/me/leagues/{league_id}/watch`](#update-watch-list) | Watch a player | `write:leagues` | 0 | `update_my_watch_list` |
| PUT | [`/v1/me/leagues/{league_id}/draft/queue`](#set-draft-queue) | Set your draft queue | `write:leagues` | 0 | `set_draft_queue` |

`GET /v1/me/league-history`

## Get your league history
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_my_league_history` · status live

The fantasy league seasons Kelly keeps for you: every season of every league you connected, kept until you delete it, even after you disconnect the league. Each league has its seasons newest first with the champion and your record; `league` and `season` return that season's whole record, and `full=true` every kept season's (the export file). Deleting is on askkelly.ai, in Ask Kelly or through Kelly MCP. Needs your own key or an OAuth token with read:league. Read only: you delete kept seasons on askkelly.ai, in Ask Kelly or through Kelly MCP. Test-mode keys read the same account as live ones.

### Parameters
- `league` string · query  
  A league: its Kelly ID (lg_) or platform:league_id. Default every league.  
  min length 3 · max length 100
- `season` integer · query  
  One season, with its whole record; needs league.  
  min 1990 · max 2100
- `full` boolean · query  
  true returns every kept season's whole record, as the export file holds it.

### Response
`200` The league seasons Kelly keeps for you.

- `object` const · required  
  Always league_history.  
  Always `"league_history"`.
- `league_history` object · required  
  The league seasons Kelly keeps for the person.
  - `leagues` array of object  
    Each kept league.
    - `league` string  
      platform:league_id, the name it keeps after a disconnect.
    - `league_id` string · nullable  
      Its Kelly ID (lg_…) while connected, else the last one.
    - `platform` string  
      The fantasy platform.
    - `name` string · nullable  
      Its latest name.
    - `connected` boolean  
      Whether the person still has it connected.
    - `season_count` integer  
      Seasons kept.
    - `seasons` array of object  
      Newest first.
      - `season` integer  
        The season.
      - `external_id` string  
        The platform's ID for that season's league.
      - `name` string · nullable  
        The league's name that season.
      - `final` boolean  
        Whether the platform marked the season complete.
      - `teams` integer  
        Teams in the league.
      - `champion` string · nullable  
        The champion's team name, once the season is final.
      - `yours` object · nullable  
        The person's team that season (team_id, name, wins, losses, ties, points_for), when Kelly knows which is theirs.
      - `saved_at` string · nullable  
        When Kelly first kept it.  
        format date-time
      - `updated_at` string · nullable  
        When it last changed.  
        format date-time
      - `record` object  
        With a season asked for: the whole season (settings, teams, each week's points and pairings, brackets, drafts), as the platform gave it.
  - `league_count` integer  
    Leagues kept.
  - `season_count` integer  
    Seasons kept in all.
  - `kept` string  
    How long Kelly keeps them: until the person deletes them.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/me/league-history
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_6478ad184e1c77fab891eda1",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/me/league-history?season=2024
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "season: name the league too.",
  "param": "league",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_71451fb129639de7976541a7",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
GET https://api.askkelly.ai/v1/me/league-history
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_history",
  "league_history": {
    "leagues": [
      {
        "league": "sleeper:1200000000000000001",
        "league_id": "lg_dzs55c9tr5hqqr0ja1tt",
        "platform": "sleeper",
        "name": "Kelly Synthetic League (Sleeper shape)",
        "connected": true,
        "seasons": [
          {
            "season": 2026,
            "external_id": "1200000000000000001",
            "name": "Kelly Synthetic League (Sleeper shape)",
            "final": false,
            "teams": 12,
            "champion": null,
            "yours": {
              "team_id": "7",
              "name": "Team 07",
              "wins": 1,
              "losses": 1,
              "ties": 0,
              "points_for": 227.1
            },
            "saved_at": "2026-10-04T17:30:00Z",
            "updated_at": "2026-10-04T17:30:00Z"
          },
          {
            "season": 2025,
            "external_id": "1200000000000000002",
            "name": "Kelly Synthetic League (Sleeper shape)",
            "final": true,
            "teams": 12,
            "champion": "Team 05 (2025)",
            "yours": {
              "team_id": "7",
              "name": "Team 07 (2025)",
              "wins": 5,
              "losses": 9,
              "ties": 0,
              "points_for": 1707.1
            },
            "saved_at": "2026-10-04T17:30:00Z",
            "updated_at": "2026-10-04T17:30:00Z"
          },
          {
            "season": 2024,
            "external_id": "1200000000000000003",
            "name": "Kelly Synthetic League (Sleeper shape)",
            "final": true,
            "teams": 12,
            "champion": "Team 08 (2024)",
            "yours": {
              "team_id": "7",
              "name": "Team 07 (2024)",
              "wins": 6,
              "losses": 8,
              "ties": 0,
              "points_for": 1688.1
            },
            "saved_at": "2026-10-04T17:30:00Z",
            "updated_at": "2026-10-04T17:30:00Z"
          }
        ],
        "season_count": 3
      }
    ],
    "league_count": 1,
    "season_count": 3,
    "kept": "until you delete it"
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_e702d29ca73112d17a399dc8"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/leagues`

## List connected leagues
scope `read:league` · 1 credit, not charged during the beta · status live

The leagues you have connected to your Kelly account: each one's ID, name, platform, season and your team's ID, oldest first. Needs your own key or an OAuth token with read:league. Read only: leagues are connected on askkelly.ai. Test-mode keys read the same account as live ones.

### Response
`200` Your connected leagues.

- `object` const · required  
  Always list.  
  Always `"list"`.
- `data` array of object · required  
  Your connected leagues.
  - `id` string  
    The league's Kelly ID (lg_): pass it to get_league.  
    pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `name` string  
    The league's name.
  - `platform` string  
    sleeper, yahoo, espn, myfantasyleague, fleaflicker, fantrax, cbs or paste.
  - `season` integer  
    Season.
  - `team_id` string · nullable  
    Your team's ID in it; null until you pick it.
- `has_more` boolean · required  
  Always false: one page holds them all.
- `next_cursor` string · nullable  
  Always null.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled)

### Example
```http
GET https://api.askkelly.ai/v1/leagues
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_967a3ad2ed41e54359d38063",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/leagues
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "lg_dzs55c9tr5hqqr0ja1tt",
      "name": "Kelly Synthetic League (Sleeper shape)",
      "platform": "sleeper",
      "season": 2026,
      "team_id": "7"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_665cab9dc815c41afa0cba6d"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/leagues/{league_id}`

## Get a connected league
scope `read:league` · 3 credits, not charged during the beta · MCP tool `get_league` · status live

One of your connected leagues as its platform last showed it: settings, the standings (a row per team in order with its manager, record, points for and against, waiver order and FAAB left, yours flagged), every roster and a week's matchups. Yours only. Needs your own key or an OAuth token with read:league. Read from the league's latest snapshot, which `as_of` dates; free_agents, matchup_win_prob, lineup and likely_drops are Kelly's, from its projections; win_history is Kelly's chance to win as it moved through the games.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

- `week` integer · query  
  The week whose matchups to return; default the platform's current week.  
  min 1 · max 23
- `include` string · query  
  Only these parts, comma-separated: settings, rosters, matchups, standings, free_agents, matchup_win_prob, lineup, likely_drops, win_history. Default all; the rest come back null.  
  min length 1 · max length 120

### Response
`200` The league.

- `object` const · required  
  Always league.  
  Always `"league"`.
- `league` object · required  
  The league (the facts Kelly MCP's get_league returns). A part left out of `include` is null.
  - `id` string · required  
    The league's Kelly ID (lg_).  
    pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `name` string · required  
    The league's name.
  - `platform` string · required  
    sleeper, yahoo, espn, myfantasyleague, fleaflicker, fantrax, cbs or paste.
  - `settings` object · required · nullable  
    The league's settings.
    - `season` integer  
      Season.
    - `week` integer  
      The platform's current week.
    - `scoring` string · nullable  
      Scoring, in words (PPR, 6-point passing TDs, …).
    - `teams` integer  
      Teams in the league.
    - `your_team_id` string · nullable  
      Your team's ID; null until you pick it.
    - `your_team` string · nullable  
      Your team's name.
    - `playoff_teams` integer · nullable  
      How many teams make the playoffs; null where the platform doesn't say.
    - `faab_budget` integer · nullable  
      Each team's FAAB budget for the season; null in a league without FAAB.
  - `standings` array of object · required · nullable  
    Every team in standings order.
    - `team_id` string  
      The team's ID in the league.
    - `rank` integer  
      Its place: by wins, then fewer losses, then points for.
    - `name` string  
      The team's name.
    - `manager` string · nullable  
      Its manager's name on the platform.
    - `wins` integer  
      Wins.
    - `losses` integer  
      Losses.
    - `ties` integer  
      Ties.
    - `points_for` number  
      Points scored, the platform's own.
    - `points_against` number · nullable  
      Points scored against it; null where the platform doesn't report them.
    - `waiver_position` integer · nullable  
      Its place in waiver order; null where the platform doesn't report it.
    - `faab_left` integer · nullable  
      FAAB dollars left; null in a league without FAAB.
    - `streak` string · nullable  
      Its current run of wins or losses as the platform writes it ("3W"); null where the platform doesn't report one.
    - `yours` boolean  
      Whether it is your team.
  - `rosters` array of object · required · nullable  
    Every team's roster, in standings order.
    - `team_id` string  
      The team's ID in the league.
    - `name` string  
      The team's name.
    - `starters` array of object  
      Its starters players, in the platform's order.
      - `name` string · nullable  
        The player's name; null for an empty slot or a player Kelly couldn't match.
      - `position` string · nullable  
        Position.
      - `team` string · nullable  
        NFL team.
      - `slot` string · nullable  
        Starters only: the lineup slot (QB, FLEX, …).
      - `empty` boolean  
        An empty starting slot.
    - `bench` array of object  
      Its bench players, in the platform's order.
      - `name` string · nullable  
        The player's name; null for an empty slot or a player Kelly couldn't match.
      - `position` string · nullable  
        Position.
      - `team` string · nullable  
        NFL team.
      - `slot` string · nullable  
        Starters only: the lineup slot (QB, FLEX, …).
      - `empty` boolean  
        An empty starting slot.
    - `ir` array of object  
      Its ir players, in the platform's order.
      - `name` string · nullable  
        The player's name; null for an empty slot or a player Kelly couldn't match.
      - `position` string · nullable  
        Position.
      - `team` string · nullable  
        NFL team.
      - `slot` string · nullable  
        Starters only: the lineup slot (QB, FLEX, …).
      - `empty` boolean  
        An empty starting slot.
    - `taxi` array of object  
      Its taxi players, in the platform's order.
      - `name` string · nullable  
        The player's name; null for an empty slot or a player Kelly couldn't match.
      - `position` string · nullable  
        Position.
      - `team` string · nullable  
        NFL team.
      - `slot` string · nullable  
        Starters only: the lineup slot (QB, FLEX, …).
      - `empty` boolean  
        An empty starting slot.
  - `matchups` array of object · required · nullable  
    The week's matchups (the current week unless `week` is sent).
    - `matchup_id` string  
      The platform's matchup number.
    - `week` integer  
      The week.
    - `teams` array of object  
      Its sides.
      - `team_id` string  
        The team's ID.
      - `name` string · nullable  
        The team's name.
      - `points` number · nullable  
        Its platform points that week so far; null before it plays.
      - `yours` boolean  
        Whether it is your team.
  - `free_agents` array of object · required · nullable  
    The league's free agents, best first: every one who beats one of your starters in some week, and the best three at each position. Null when Kelly has no projections for the league's week.
    - `player_id` string  
      The player's Kelly ID (plr_); for a defense, its team's Kelly ID.
    - `name` string · nullable  
      The player's name.
    - `position` string  
      Position (QB, RB, WR, TE, K, DST).
    - `team` string · nullable  
      NFL team.
    - `rank` integer  
      His place in the list, best first.
    - `value` number  
      Kelly's value: his projected points above your weakest starter at a slot he fits, summed over the rest of the season in the weeks he beats that starter, times his chance to play.
    - `ros_points` number  
      His projected points over the rest of the season.
    - `points` number  
      His projected points this week.
    - `p_active` number  
      His chance to play this week.
    - `weeks_ahead` integer  
      The weeks he is projected to beat that starter.
    - `replaces` string · nullable  
      The starter of yours he is measured against; null when you have no team picked or no starter at a slot he fits.
    - `replaces_ros_points` number · nullable  
      That starter's projected points over the rest of the season.
    - `bid` integer · nullable  
      Kelly's FAAB bid in whole dollars, from the FAAB you have left; null in a league without FAAB.
    - `bid_low` integer · nullable  
      The low end of the bids within 10% of the best one.
    - `bid_high` integer · nullable  
      The high end of that range.
    - `p_win` number · nullable  
      The chance the bid wins the claim (Kelly's price model).
    - `bidders` number · nullable  
      The expected number of teams bidding on him, you included (atlas WV4: each rival's chance from how much he would improve its starters and its manager's own claim rate, fitted on the league's claims, failed ones included). Null before the league's first claim.
    - `rivals` array of object · nullable  
      The three rivals likeliest to bid on him, likeliest first.
      - `team_id` string  
        The rival's team ID.
      - `name` string · nullable  
        The rival's team name.
      - `p_bid` number  
        His chance to bid on the player.
      - `bid` integer · nullable  
        His likely bid in whole dollars (atlas WV5: the bidder-count curve times his own past bids, capped at his FAAB left); null outside FAAB.
      - `bid_low` integer · nullable  
        The low end of his bid (1 in 5 lower); null under three bids in the league.
      - `bid_high` integer · nullable  
        The high end (1 in 5 higher).
    - `p_win_vs_rivals` number · nullable  
      The chance Kelly's bid beats every rival's (atlas WV5), a tie lost; null outside FAAB.
    - `p_claimed_ahead` number · nullable  
      Rolling waivers: the chance a team ahead of you in the waiver order claims him; null in a FAAB league.
  - `matchup_win_prob` array of object · required · nullable  
    The week's matchups (the current week unless `week` is sent) with each side's chance to win: Monte Carlo over every starter's points, players in the same NFL game drawn together, finished games at their actual points, a game in progress at the points so far plus the share still to come at that minute, so it moves through the games (atlas MU4). Null when Kelly has no projections for the week.
    - `matchup_id` string  
      The platform's matchup number.
    - `week` integer  
      The week.
    - `teams` array of object  
      Its two sides.
      - `team_id` string  
        The team's ID.
      - `name` string · nullable  
        The team's name.
      - `p_win` number  
        Kelly's chance this side wins the matchup (a tie counts half), from its starters as set.
      - `points` number  
        Kelly's median for its total.
      - `points_low` number  
        The low end of its total (1 in 10 lower).
      - `points_high` number  
        The high end of its total (1 in 10 higher).
      - `spread` number  
        Kelly's fair spread for this side, as a book writes it: the favourite's is negative (its projected margin), the underdog's positive.
      - `moneyline` integer · nullable  
        Kelly's fair American moneyline for this side, from its chance to win with no margin; null when the result is settled.
      - `wants` string · nullable  
        steady for the favourite (less spread in the scores helps it), volatile for the underdog; null for an even matchup.  
        One of: `steady`, `volatile` (open: new values may be added).
      - `p_win_per_sd_point` number · nullable  
        The change in this side's chance to win for each extra point of spread in the margin (kmath F29.2): negative for the favourite.
      - `to_play` integer  
        Its starters whose game has not kicked off.
      - `playing` integer  
        Its starters whose game is in progress.
      - `done` integer  
        Its starters whose game is over.
      - `points_so_far` number  
        Its points so far: finished games at their actual points, games in progress at Kelly's points from the plays under the league's rules, else the platform's live points.
      - `points_to_come` number  
        Kelly's mean for its points still to come (a starter in progress: the share of a game's points still to come at that minute, fitted on 2019-2025 play-by-play).
      - `yours` boolean  
        Whether it is your team.
    - `total` number  
      Kelly's fair total: the two sides' projected points together.
    - `slots` array of object  
      The lineups slot by slot, in the first side's order.
      - `slot` string · nullable  
        The slot (QB, RB, FLEX, …).
      - `players` array of string  
        The first side's player, then the second side's.
      - `points` array of number  
        Each player's projected final points, in the same order.
      - `now` array of number  
        Each player's points so far, in the same order.
      - `now_source` array of string  
        Each player's source, in the same order.
      - `state` array of string  
        Each player's game state, in the same order.
      - `has_projection` array of boolean  
        Each player's flag, in the same order.
      - `projection_source` array of string  
        Each player's projection source, in the same order.
      - `p_first` number  
        Kelly's chance the first side's player outscores the second side's.
      - `games` array of object  
        Each player's NFL game and stat line, in the same order (ADR-K514).
        - `game_id` string  
          The game's ID (gm_).
        - `status` string  
          scheduled, live, final, postponed, cancelled or suspended.
        - `kickoff_at` string · nullable  
          Kickoff (RFC 3339).  
          format date-time
        - `home` boolean  
          Whether his team is at home.
        - `opponent` string · nullable  
          The other team's abbreviation.
        - `score` array of integer · nullable  
          His team's points, then the opponent's; null before the game.
        - `period` string · nullable  
          The period.
        - `clock` string · nullable  
          The game clock.
        - `has_ball` boolean · nullable  
          Whether his team has the ball; null when no source says.
        - `situation` object · nullable  
          The live situation, football only; null when no source sends one.
          - `down` integer · nullable  
            The down.
          - `distance` integer · nullable  
            Yards to go for a first down.
          - `yards_to_goal` integer · nullable  
            Yards from the ball to the goal the offence attacks.
          - `goal_to_go` boolean · nullable  
            Whether it is goal to go.
          - `red_zone` boolean · nullable  
            Whether the ball is inside the 20.
          - `spot` object · nullable  
            Where the ball is.
            - `yard` integer  
              The yard line (1 to 50).
            - `own_half` boolean · nullable  
              Whether the ball is on his team's half; null at midfield.
    - `swing_players` array of object  
      Every unlocked starter on both sides, biggest swing first.
      - `team_id` string  
        His team's ID.
      - `name` string · nullable  
        His name.
      - `slot` string · nullable  
        His slot.
      - `low` number  
        His 25th-percentile points.
      - `high` number  
        His 75th-percentile points.
      - `swing` number  
        His team's chance to win when he scores at or above `high`, less its chance when he scores at or below `low`.
    - `totals_rho` number · nullable  
      The correlation of the two sides' totals over Kelly's draws (atlas MU6); null when a total is settled.
    - `shared_games` array of object  
      Every pair of opposing starters in the same NFL game, the strongest correlation first.
      - `nfl_game` string  
        The NFL game, as its two teams' abbreviations (sorted, joined by ·).
      - `players` array of string  
        The first side's player, then the second side's.
      - `slots` array of string  
        Their slots, in the same order.
      - `rho` number · nullable  
        The correlation of their points over Kelly's draws: positive, they rise and fall together and cancel out in this matchup; null when one is settled.
  - `lineup` object · required · nullable  
    Your best lineup for the week (the current week unless `week` is sent): every legal lineup scored on the same draws for its chance to beat the opponent's likely lineup, the swaps from your lineup as set, and the checks before kickoff. Null when you have no team picked or Kelly has no projections for the week.
    - `week` integer  
      The week.
    - `verdict` string  
      keep (your lineup as set is the best, or within 0.5% of it, or the difference is inside the simulation's noise) or change.
    - `p_win` number  
      Your chance to win with the best lineup against the opponent's likely lineup.
    - `p_win_as_set` number  
      Your chance to win with the lineup as set.
    - `p_win_gain` number  
      The best lineup's gain in chance to win over the lineup as set.
    - `p_win_gain_low` number  
      The gain's 80% interval, low end.
    - `p_win_gain_high` number  
      The gain's 80% interval, high end.
    - `best` object  
      The lineup with the highest chance to win, from every legal lineup.
      - `starters` array of object  
        Its starters by slot.
        - `slot` string  
          The lineup slot (QB, RB, WR, TE, FLEX, K, DEF, …).
        - `player_id` string · nullable  
          The player's Kelly ID (plr_); for a defense, its team's Kelly ID.
        - `name` string · nullable  
          The player's name.
        - `position` string · nullable  
          Position.
        - `points` number  
          Kelly's median for his points this week.
        - `points_low` number  
          The low end (1 in 5 lower).
        - `points_high` number  
          The high end (1 in 5 higher).
      - `points` number  
        Kelly's median for the lineup's total.
      - `points_low` number  
        The low end of the total (1 in 5 lower).
      - `points_high` number  
        The high end of the total (1 in 5 higher).
    - `as_set` object  
      Your lineup as set on the platform.
      - `starters` array of object  
        Its starters by slot.
        - `slot` string  
          The lineup slot (QB, RB, WR, TE, FLEX, K, DEF, …).
        - `player_id` string · nullable  
          The player's Kelly ID (plr_); for a defense, its team's Kelly ID.
        - `name` string · nullable  
          The player's name.
        - `position` string · nullable  
          Position.
        - `points` number  
          Kelly's median for his points this week.
        - `points_low` number  
          The low end (1 in 5 lower).
        - `points_high` number  
          The high end (1 in 5 higher).
      - `points` number  
        Kelly's median for the lineup's total.
      - `points_low` number  
        The low end of the total (1 in 5 lower).
      - `points_high` number  
        The high end of the total (1 in 5 higher).
    - `start` array of object  
      Players to start: in the best lineup, not in the lineup as set.
      - `player_id` string · nullable  
        The player's Kelly ID.
      - `name` string · nullable  
        The player's name.
    - `sit` array of object  
      Players to sit: in the lineup as set, not in the best lineup.
      - `player_id` string · nullable  
        The player's Kelly ID.
      - `name` string · nullable  
        The player's name.
    - `bench` array of object  
      Everyone left out of the best lineup, best first.
      - `player_id` string · nullable  
        The player's Kelly ID.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        Position.
      - `points` number  
        Kelly's median for his points.
      - `points_low` number  
        The low end (1 in 5 lower).
      - `points_high` number  
        The high end (1 in 5 higher).
    - `opponent` object  
      The opponent's lineups.
      - `team_id` string  
        The opponent's team ID.
      - `name` string · nullable  
        The opponent's name.
      - `history_weeks` integer  
        The past weeks of his lineups his likely lineup is drawn from (up to 4).
      - `likely` object  
        His likely lineup: the players he started most over his last four weeks, else his lineup as set.
        - `starters` array of object  
          Its starters by slot.
          - `slot` string  
            The lineup slot (QB, RB, WR, TE, FLEX, K, DEF, …).
          - `player_id` string · nullable  
            The player's Kelly ID (plr_); for a defense, its team's Kelly ID.
          - `name` string · nullable  
            The player's name.
          - `position` string · nullable  
            Position.
          - `points` number  
            Kelly's median for his points this week.
          - `points_low` number  
            The low end (1 in 5 lower).
          - `points_high` number  
            The high end (1 in 5 higher).
        - `points` number  
          Kelly's median for the lineup's total.
        - `points_low` number  
          The low end of the total (1 in 5 lower).
        - `points_high` number  
          The high end of the total (1 in 5 higher).
      - `as_set` object  
        His lineup as set.
        - `points` number  
          Kelly's median for the lineup's total.
        - `points_low` number  
          The low end of the total (1 in 5 lower).
        - `points_high` number  
          The high end of the total (1 in 5 higher).
      - `ceiling` object  
        His highest-median lineup, and your chance to win against it with your best lineup.
        - `points` number  
          Kelly's median for the lineup's total.
        - `points_low` number  
          The low end of the total (1 in 5 lower).
        - `points_high` number  
          The high end of the total (1 in 5 higher).
        - `p_win` number  
          Your chance to win against it.
    - `checks` array of object  
      What is wrong with the lineup as set, one per problem; players whose game has kicked off are left out.
      - `kind` string  
        empty_slot, unmatched (a player Kelly can't identify), bye, out (ruled out, inactive or on a reserve list), at_risk (doubtful or questionable), ir_eligible (an open IR slot he can move to) or late_flex (a starter in a fixed slot plays later than your FLEX: swap them and the FLEX choice stays open longer).
      - `slot` string · nullable  
        His slot.
      - `player` string · nullable  
        The player's name.
      - `status` string · nullable  
        The injury report's word (out, doubtful, questionable, inactive).
      - `kickoff` string · nullable  
        His game's kickoff (ISO 8601).
      - `fix` object · nullable  
        The bench player who fixes it (or, for late_flex, the starter to swap into FLEX).
        - `player_id` string · nullable  
          The player's Kelly ID.
        - `name` string · nullable  
          The player's name.
        - `points` number · nullable  
          Kelly's median for his points this week.
        - `slot` string · nullable  
          late_flex: the slot he starts in now.
        - `kickoff` string · nullable  
          late_flex: his game's kickoff (ISO 8601).
    - `lineups_scored` integer  
      The legal lineups scored.
  - `likely_drops` object · required · nullable  
    League mates' players likeliest to be dropped before next week (atlas WV21): P(drop) from where each sits on his team's roster by rest-of-season points and the manager's own drop rate, fitted on the league's drops this season. Your team is left out. Null before the league's first final week.
    - `week` integer  
      The week.
    - `expected` number  
      The drops expected across the other teams before next week.
    - `player_weeks` integer  
      The rostered player-weeks the fit saw.
    - `drops_seen` integer  
      The drops among them.
    - `players` array of object  
      The ten likeliest, likeliest first.
      - `player_id` string · nullable  
        The player's Kelly ID (plr_); for a defense, its team's Kelly ID.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        Position.
      - `team_id` string  
        The team that has him.
      - `team` string · nullable  
        That team's name.
      - `ros_points` number  
        His projected points over the rest of the season.
      - `p_drop` number  
        Kelly's chance that team drops him before next week.
  - `win_history` array of object · required · nullable  
    Each matchup's chance to win as it moved through the week (the current week unless `week` is sent): one tick each time a side's chance moves a whole point while the games are on. Empty before the week's first live number.
    - `matchup_id` string  
      The matchup's ID, as in matchup_win_prob.
    - `week` integer  
      The week.
    - `team_ids` array of string  
      The two teams, the first as in matchup_win_prob.
    - `ticks` array of object  
      Every move, oldest first: the first is the week's first number.
      - `at` string  
        When Kelly worked it out (RFC 3339).
      - `p_win` array of number  
        Each team's chance, in `team_ids` order.
      - `points` array of number  
        Each team's points so far, in `team_ids` order.
  - `links` object · required  
    The league's pages on its own platform, by page (league, matchup, standings, team, players, claims, trade, trades, draft; only those the platform has), for your team. Kelly acts in a league only through these: you make the move on the platform.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_00000000000000000000
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No league with that league_id is yours.",
  "param": "league_id",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_5acedae574ab5dd7de0206fd",
  "retryable": false,
  "display_message": "That could not be found."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt?include=settings,standings
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league",
  "league": {
    "id": "lg_dzs55c9tr5hqqr0ja1tt",
    "name": "Kelly Synthetic League (Sleeper shape)",
    "platform": "sleeper",
    "settings": {
      "season": 2026,
      "week": 3,
      "scoring": "PPR · 12-team · 1QB",
      "teams": 12,
      "your_team_id": "7",
      "your_team": "Team 07",
      "playoff_teams": 6,
      "faab_budget": 100
    },
    "standings": [
      {
        "team_id": "9",
        "rank": 1,
        "name": "Team 09",
        "manager": "owner09",
        "wins": 2,
        "losses": 0,
        "ties": 0,
        "points_for": 218.7,
        "points_against": 174,
        "waiver_position": 10,
        "faab_left": 80,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "2",
        "rank": 2,
        "name": "Team 02",
        "manager": "owner02",
        "wins": 2,
        "losses": 0,
        "ties": 0,
        "points_for": 218.6,
        "points_against": 200,
        "waiver_position": 11,
        "faab_left": 73,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "10",
        "rank": 3,
        "name": "Team 10",
        "manager": "owner10",
        "wins": 2,
        "losses": 0,
        "ties": 0,
        "points_for": 182,
        "points_against": 148,
        "waiver_position": 3,
        "faab_left": 85,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "7",
        "rank": 4,
        "name": "Team 07",
        "manager": "owner07",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 227.1,
        "points_against": 227,
        "waiver_position": 12,
        "faab_left": 96,
        "streak": null,
        "yours": true
      },
      {
        "team_id": "4",
        "rank": 5,
        "name": "Team 04",
        "manager": "owner04",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 210.2,
        "points_against": 183,
        "waiver_position": 9,
        "faab_left": 77,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "8",
        "rank": 6,
        "name": "Team 08",
        "manager": "owner08",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 192.4,
        "points_against": 200,
        "waiver_position": 5,
        "faab_left": 100,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "1",
        "rank": 7,
        "name": "Team 01",
        "manager": "owner01",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 192.3,
        "points_against": 165,
        "waiver_position": 6,
        "faab_left": 100,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "3",
        "rank": 8,
        "name": "Team 03",
        "manager": "owner03",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 183.9,
        "points_against": 208,
        "waiver_position": 4,
        "faab_left": 100,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "5",
        "rank": 9,
        "name": "Team 05",
        "manager": "owner05",
        "wins": 1,
        "losses": 1,
        "ties": 0,
        "points_for": 174.5,
        "points_against": 156,
        "waiver_position": 2,
        "faab_left": 92,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "11",
        "rank": 10,
        "name": "Team 11",
        "manager": "owner11",
        "wins": 0,
        "losses": 2,
        "ties": 0,
        "points_for": 208.3,
        "points_against": 245,
        "waiver_position": 8,
        "faab_left": 84,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "6",
        "rank": 11,
        "name": "Team 06",
        "manager": "owner06",
        "wins": 0,
        "losses": 2,
        "ties": 0,
        "points_for": 200.8,
        "points_against": 253,
        "waiver_position": 7,
        "faab_left": 91,
        "streak": null,
        "yours": false
      },
      {
        "team_id": "12",
        "rank": 12,
        "name": "Team 12",
        "manager": "owner12",
        "wins": 0,
        "losses": 2,
        "ties": 0,
        "points_for": 173.6,
        "points_against": 218,
        "waiver_position": 1,
        "faab_left": 69,
        "streak": null,
        "yours": false
      }
    ],
    "rosters": null,
    "matchups": null,
    "free_agents": null,
    "matchup_win_prob": null,
    "lineup": null,
    "likely_drops": null,
    "win_history": null,
    "links": {
      "league": "https://sleeper.com/leagues/1200000000000000001/league",
      "matchup": "https://sleeper.com/leagues/1200000000000000001/matchup",
      "standings": "https://sleeper.com/leagues/1200000000000000001/league",
      "team": "https://sleeper.com/leagues/1200000000000000001/team",
      "players": "https://sleeper.com/leagues/1200000000000000001/players",
      "claims": "https://sleeper.com/leagues/1200000000000000001/players",
      "trade": "https://sleeper.com/leagues/1200000000000000001/team",
      "trades": "https://sleeper.com/leagues/1200000000000000001/league",
      "draft": "https://sleeper.com/leagues/1200000000000000001/league"
    }
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_f0c188052ef8d69ab77d57c3"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/leagues/{league_id}/sync`

## Get how fresh a league is
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_league_sync` · status live

When Kelly last read one of your connected leagues from its platform, how old each part is (settings, teams, standings, rosters, lineups, matchups, transactions, waivers, traded picks, draft), how often Kelly reads it now and when next, and any trouble. The same facts as Kelly MCP's get_league_sync. Needs your own key or an OAuth token with read:league. Read only.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

### Response
`200` How fresh the league is.

- `object` const · required  
  Always league_sync.  
  Always `"league_sync"`.
- `league_sync` object · required  
  How fresh Kelly's copy of a connected league is, part by part, and when Kelly reads it next.
  - `league` string · nullable  
    The league's ID (lg_…).
  - `platform` string · nullable  
    sleeper, yahoo, mfl, fleaflicker or paste (a pasted league doesn't sync).
  - `contract` string · nullable  
    The league model contract's version.
  - `tier` string · nullable  
    How often Kelly reads it now: waiver_run (every minute), live_viewing (30 s, open while a game is live), viewing (2 min), draft (2 min), live (5 min), idle (15 min), corrections (daily, Tue to Fri), offseason (daily) or stopped.
  - `next_sync_at` string · nullable  
    When Kelly reads it next.  
    format date-time
  - `last_sync` object · nullable  
    The last good read.
    - `at` string · nullable  
      When.  
      format date-time
    - `outcome` string · nullable  
      changed, same, failed or skipped.
    - `age_s` integer · nullable  
      Seconds since then.
  - `sections` object  
    Each part's age, by name: settings, teams, standings, rosters, lineups, matchups, transactions, waivers, traded_picks, draft.
  - `state` string · nullable  
    ok, syncing, behind, backing_off (the platform is failing; Kelly retries with longer waits), stopped (lost access: reconnect), never, or manual (a pasted league).
  - `waiver_window_at` string · nullable  
    The waiver run Kelly times its 1-minute reads to.  
    format date-time
  - `stopped_reason` string · nullable  
    Why syncing stopped.
  - `last_error` string · nullable  
    The last failure, while failures continue.
  - `note` string · nullable  
    A note for a pasted league.
  - `conflicts` array of object  
    Where Kelly's own scores and the platform's final scores differ by more than 0.1 point, or a stat correction changed a result (ADR-K415), newest week first.
    - `kind` string  
      score_gap (a final week's totals differ), stat_correction (the result changed) or live_gap (game day: a finished player's Kelly re-score differs from the platform's, which is the number shown).
    - `week` integer  
      The week.
    - `team_id` string  
      The platform's team number, as text.
    - `kelly_points` number · nullable  
      Kelly's points from its own box score.
    - `platform_points` number · nullable  
      The platform's final points.
    - `gap` number · nullable  
      Kelly's less the platform's.
    - `cause` string · nullable  
      The cause Kelly found.
    - `result_flipped` boolean  
      Whether a stat correction changed the result.
    - `players` array of object  
      The starters whose two numbers differ.
      - `source_id` string  
        The platform's player ID.
      - `name` string · nullable  
        The player's name.
      - `slot` string · nullable  
        The lineup slot.
      - `points` number · nullable  
        Kelly's points.
      - `platform_points` number · nullable  
        The platform's points.
      - `gap` number · nullable  
        Kelly's less the platform's.
      - `source` string  
        Where Kelly's number came from: stats, plays, platform or none.
      - `entity_id` string · nullable  
        Kelly's player ID.
      - `position` string · nullable  
        The player's position.
    - `checked_at` string · nullable  
      When.  
      format date-time
  - `accuracy` object · nullable  
    Kelly's own scores for this league: the last checked week against the platform's final scores, the season so far, and this week's Kelly live points (ADR-K415). Null before any check or live score.
    - `label` string  
      What Kelly's own points are called where they show: Kelly live.
    - `platform` string · nullable  
      The platform checked against.
    - `week` integer · nullable  
      The last checked week.
    - `checked_at` string · nullable  
      When it was checked.  
      format date-time
    - `tolerance` number  
      The largest gap that counts as a match, in points (0.1).
    - `last_week` object · nullable  
      The last checked week's teams.
      - `teams` integer  
        Teams checked.
      - `matched` integer  
        Teams whose scores matched within 0.1 point.
      - `differs` integer  
        Teams whose scores differ.
      - `largest_gap` number  
        The largest team gap, in points.
      - `causes` object  
        Differences by cause: unmatched_player, dst, rounding, stat_correction, platform_rescore, settings_changed, unknown.
      - `result_flipped` integer  
        Results a stat correction changed.
    - `season` object · nullable  
      Every checked team-week this season.
      - `teams` integer  
        Teams checked.
      - `matched` integer  
        Teams whose scores matched within 0.1 point.
      - `differs` integer  
        Teams whose scores differ.
    - `live` object · nullable  
      This week's Kelly live points.
      - `week` integer  
        The week in play.
      - `computed_at` string · nullable  
        When Kelly last scored it.  
        format date-time
      - `teams` object  
        By team ID.
  - `host` object · nullable  
    Whether the platform is answering with real scores, and whose scores to show (ADR-K501). Null for a pasted league.
    - `status` string  
      ok; not_responding (two reads in a row failed); zeros (while games are on, the platform shows 0 for teams Kelly's own scoring has at 5 or more); recovered (reads work again after failing this week, for 3 hours).
    - `since` string · nullable  
      When it stopped answering.  
      format date-time
    - `back_at` string · nullable  
      When it answered again (recovered).  
      format date-time
    - `score_source` string  
      Whose scores to show: platform, or kelly_live (Kelly's own live points, from accuracy.live) while it is down.
    - `platform` string · nullable  
      The platform.
    - `matched` integer · nullable  
      recovered: teams whose platform points match Kelly's within 0.1 point.
    - `teams` integer · nullable  
      recovered: teams both have points for.
    - `words` string  
      One line for the person; empty when all is well.
  - `leagues` array of object  
    The person's connected leagues, when they have several and named none: call again with one.
    - `league_id` string  
      Its ID (lg_…).
    - `name` string  
      Its name.
    - `platform` string  
      Its platform.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/sync
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_ee49c7b44c63157e43361cb0",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/sync
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_sync",
  "league_sync": {
    "league": "lg_dzs55c9tr5hqqr0ja1tt",
    "platform": "sleeper",
    "contract": "1.0",
    "tier": "idle",
    "next_sync_at": "2026-10-04T17:45:00Z",
    "last_sync": {
      "at": "2026-10-04T17:30:00Z",
      "outcome": null,
      "age_s": 0
    },
    "sections": {
      "draft": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "lineups": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "matchups": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "rosters": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "settings": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "standings": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "teams": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "traded_picks": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "transactions": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      },
      "waivers": {
        "as_of": "2026-10-04T17:30:00Z",
        "age_s": 0,
        "changed_at": "2026-10-04T17:30:00Z"
      }
    },
    "state": "ok",
    "conflicts": [],
    "accuracy": null,
    "host": {
      "status": "ok",
      "since": null,
      "back_at": null,
      "score_source": "platform",
      "platform": "sleeper",
      "matched": null,
      "teams": null,
      "words": ""
    },
    "waiver_window_at": "2026-10-07T16:00:00Z",
    "stopped_reason": null,
    "last_error": null
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_a88954466b4510c859ff8087"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`POST /v1/leagues/{league_id}/sync`

## Read a league again now
scope `read:league` · 0 credits, not charged during the beta · MCP tool `refresh_my_league` · status live

Reads one of your connected leagues from its platform now and stores it, then returns how fresh each part is. The same facts as Kelly MCP's refresh_my_league. Needs your own key or an OAuth token with read:league. Changes nothing you set: Kelly reads the platform and stores what it says, as it does on its own every few minutes. A read in the last 20 seconds is reused.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

Body, `application/json`:

- `mode` string  
  refresh reads the league now; viewing keeps it on the 2-minute tier for 3 minutes (a view that's open), reading it at once when its rosters are over 2 minutes old.  
  One of: `refresh`, `viewing` (open: new values may be added).  
  default "refresh"

### Response
`200` How fresh the league is after the read.

- `object` const · required  
  Always league_sync.  
  Always `"league_sync"`.
- `league_sync` object · required  
  How fresh Kelly's copy of a connected league is, part by part, and when Kelly reads it next.
  - `league` string · nullable  
    The league's ID (lg_…).
  - `platform` string · nullable  
    sleeper, yahoo, mfl, fleaflicker or paste (a pasted league doesn't sync).
  - `contract` string · nullable  
    The league model contract's version.
  - `tier` string · nullable  
    How often Kelly reads it now: waiver_run (every minute), live_viewing (30 s, open while a game is live), viewing (2 min), draft (2 min), live (5 min), idle (15 min), corrections (daily, Tue to Fri), offseason (daily) or stopped.
  - `next_sync_at` string · nullable  
    When Kelly reads it next.  
    format date-time
  - `last_sync` object · nullable  
    The last good read.
    - `at` string · nullable  
      When.  
      format date-time
    - `outcome` string · nullable  
      changed, same, failed or skipped.
    - `age_s` integer · nullable  
      Seconds since then.
  - `sections` object  
    Each part's age, by name: settings, teams, standings, rosters, lineups, matchups, transactions, waivers, traded_picks, draft.
  - `state` string · nullable  
    ok, syncing, behind, backing_off (the platform is failing; Kelly retries with longer waits), stopped (lost access: reconnect), never, or manual (a pasted league).
  - `waiver_window_at` string · nullable  
    The waiver run Kelly times its 1-minute reads to.  
    format date-time
  - `stopped_reason` string · nullable  
    Why syncing stopped.
  - `last_error` string · nullable  
    The last failure, while failures continue.
  - `note` string · nullable  
    A note for a pasted league.
  - `conflicts` array of object  
    Where Kelly's own scores and the platform's final scores differ by more than 0.1 point, or a stat correction changed a result (ADR-K415), newest week first.
    - `kind` string  
      score_gap (a final week's totals differ), stat_correction (the result changed) or live_gap (game day: a finished player's Kelly re-score differs from the platform's, which is the number shown).
    - `week` integer  
      The week.
    - `team_id` string  
      The platform's team number, as text.
    - `kelly_points` number · nullable  
      Kelly's points from its own box score.
    - `platform_points` number · nullable  
      The platform's final points.
    - `gap` number · nullable  
      Kelly's less the platform's.
    - `cause` string · nullable  
      The cause Kelly found.
    - `result_flipped` boolean  
      Whether a stat correction changed the result.
    - `players` array of object  
      The starters whose two numbers differ.
      - `source_id` string  
        The platform's player ID.
      - `name` string · nullable  
        The player's name.
      - `slot` string · nullable  
        The lineup slot.
      - `points` number · nullable  
        Kelly's points.
      - `platform_points` number · nullable  
        The platform's points.
      - `gap` number · nullable  
        Kelly's less the platform's.
      - `source` string  
        Where Kelly's number came from: stats, plays, platform or none.
      - `entity_id` string · nullable  
        Kelly's player ID.
      - `position` string · nullable  
        The player's position.
    - `checked_at` string · nullable  
      When.  
      format date-time
  - `accuracy` object · nullable  
    Kelly's own scores for this league: the last checked week against the platform's final scores, the season so far, and this week's Kelly live points (ADR-K415). Null before any check or live score.
    - `label` string  
      What Kelly's own points are called where they show: Kelly live.
    - `platform` string · nullable  
      The platform checked against.
    - `week` integer · nullable  
      The last checked week.
    - `checked_at` string · nullable  
      When it was checked.  
      format date-time
    - `tolerance` number  
      The largest gap that counts as a match, in points (0.1).
    - `last_week` object · nullable  
      The last checked week's teams.
      - `teams` integer  
        Teams checked.
      - `matched` integer  
        Teams whose scores matched within 0.1 point.
      - `differs` integer  
        Teams whose scores differ.
      - `largest_gap` number  
        The largest team gap, in points.
      - `causes` object  
        Differences by cause: unmatched_player, dst, rounding, stat_correction, platform_rescore, settings_changed, unknown.
      - `result_flipped` integer  
        Results a stat correction changed.
    - `season` object · nullable  
      Every checked team-week this season.
      - `teams` integer  
        Teams checked.
      - `matched` integer  
        Teams whose scores matched within 0.1 point.
      - `differs` integer  
        Teams whose scores differ.
    - `live` object · nullable  
      This week's Kelly live points.
      - `week` integer  
        The week in play.
      - `computed_at` string · nullable  
        When Kelly last scored it.  
        format date-time
      - `teams` object  
        By team ID.
  - `host` object · nullable  
    Whether the platform is answering with real scores, and whose scores to show (ADR-K501). Null for a pasted league.
    - `status` string  
      ok; not_responding (two reads in a row failed); zeros (while games are on, the platform shows 0 for teams Kelly's own scoring has at 5 or more); recovered (reads work again after failing this week, for 3 hours).
    - `since` string · nullable  
      When it stopped answering.  
      format date-time
    - `back_at` string · nullable  
      When it answered again (recovered).  
      format date-time
    - `score_source` string  
      Whose scores to show: platform, or kelly_live (Kelly's own live points, from accuracy.live) while it is down.
    - `platform` string · nullable  
      The platform.
    - `matched` integer · nullable  
      recovered: teams whose platform points match Kelly's within 0.1 point.
    - `teams` integer · nullable  
      recovered: teams both have points for.
    - `words` string  
      One line for the person; empty when all is well.
  - `leagues` array of object  
    The person's connected leagues, when they have several and named none: call again with one.
    - `league_id` string  
      Its ID (lg_…).
    - `name` string  
      Its name.
    - `platform` string  
      Its platform.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found) · [`payload_too_large`](/problems/payload_too_large) · [`upstream_error`](/problems/upstream_error) · [`upstream_timeout`](/problems/upstream_timeout)

### Example
```http
POST https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/sync
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "mode": "refresh"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_f403b9764e56cd2658c50ce5",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
POST https://api.askkelly.ai/v1/leagues/lg_00000000000000000000/sync
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "mode": "refresh"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such league.",
  "param": "league",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_9b2322083bb23619f2e2f6d2",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`GET /v1/leagues/{league_id}/teams`

## Get a team in your league
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_league_team` · status live

One team in one of your connected leagues, yours unless `team` names another: its place, record and points, its roster by section with this week's points, this week's matchup with Kelly's chance to win, how its manager runs it and its latest moves; for your own team Kelly's lineup check too. Read only. Needs your own key or an OAuth token with read:league. Read from the league's latest sync, which `as_of` dates; a league mate's team is read inside your own league only.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

- `team` string · query  
  A team: its name, manager or team ID. Default your own.  
  min length 1 · max length 100
- `angles` boolean · query  
  true adds this week's game lines for the team's starters; left out, your betting angles setting decides (off unless you turned it on).

### Response
`200` The team.

- `object` const · required  
  Always league_team.  
  Always `"league_team"`.
- `league_team` object · required  
  One team in the person's league.
  - `league` object  
    The league and how old Kelly's copy is.
    - `id` string  
      The league's Kelly ID (lg_…).
    - `name` string  
      The league's name.
    - `platform` string  
      sleeper, yahoo, myfantasyleague, fleaflicker or paste.
    - `season` integer  
      The season.
    - `week` integer  
      The platform's current week.
    - `scoring` string · nullable  
      The scoring in words, such as Half-PPR · 12-team · 1QB.
    - `as_of` string · nullable  
      When Kelly last read the league from its platform.  
      format date-time
    - `age_s` integer · nullable  
      Seconds since then.
  - `team` object  
    The team's row in the standings: rank, name, manager, wins, losses, ties, points_for, points_against, waiver_position, faab_left, streak, yours.
    - `team_id` string  
      The team's ID in the league.
  - `yours` boolean  
    Whether this is the person's own team.
  - `teams` array of object  
    Every team, in standings order, for a picker.
    - `team_id` string · nullable  
      The team's ID in the league.
    - `name` string · nullable  
      The team's name.
    - `manager` string · nullable  
      Its manager's name on the platform.
    - `yours` boolean  
      The person's own team.
  - `week` integer  
    The week these facts are for: the league's week unless the call asked for another (ADR-K519).
  - `weeks` object  
    The league's weeks, for a week stepper.
    - `first` integer  
      The schedule's first week.
    - `last` integer  
      The schedule's last week.
    - `current` integer  
      The league's week now.
  - `roster` object · nullable  
    The roster by section. For a finished week, the lineup the manager set and each player's points that week (projected, opponent and position_rank null), or null when the platform keeps no lineup for the week; for a later week, the roster as it stands with that week's projections.
    - `starters` array of object  
      Starters in slot order.
      - `player_id` string · nullable  
        The player's Kelly ID, when Kelly matched him.
      - `name` string · nullable  
        His name; null for an empty slot.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `slot` string · nullable  
        The starting slot (starters only).
      - `empty` boolean  
        An empty starting slot.
      - `points` number · nullable  
        His points this week as the platform shows them, live through games.
      - `projected` number · nullable  
        Kelly's mean projection for the week in the league's scoring; 0 on a bye; null when Kelly doesn't project him.
      - `opponent` string · nullable  
        His NFL opponent this week, or BYE.
      - `position_rank` string · nullable  
        His rank by that projection among every projected player at his position, e.g. WR9.
    - `bench` array of object  
      The bench.
      - `player_id` string · nullable  
        The player's Kelly ID, when Kelly matched him.
      - `name` string · nullable  
        His name; null for an empty slot.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `slot` string · nullable  
        The starting slot (starters only).
      - `empty` boolean  
        An empty starting slot.
      - `points` number · nullable  
        His points this week as the platform shows them, live through games.
      - `projected` number · nullable  
        Kelly's mean projection for the week in the league's scoring; 0 on a bye; null when Kelly doesn't project him.
      - `opponent` string · nullable  
        His NFL opponent this week, or BYE.
      - `position_rank` string · nullable  
        His rank by that projection among every projected player at his position, e.g. WR9.
    - `ir` array of object  
      Injured reserve.
      - `player_id` string · nullable  
        The player's Kelly ID, when Kelly matched him.
      - `name` string · nullable  
        His name; null for an empty slot.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `slot` string · nullable  
        The starting slot (starters only).
      - `empty` boolean  
        An empty starting slot.
      - `points` number · nullable  
        His points this week as the platform shows them, live through games.
      - `projected` number · nullable  
        Kelly's mean projection for the week in the league's scoring; 0 on a bye; null when Kelly doesn't project him.
      - `opponent` string · nullable  
        His NFL opponent this week, or BYE.
      - `position_rank` string · nullable  
        His rank by that projection among every projected player at his position, e.g. WR9.
    - `taxi` array of object  
      The taxi squad (dynasty leagues).
      - `player_id` string · nullable  
        The player's Kelly ID, when Kelly matched him.
      - `name` string · nullable  
        His name; null for an empty slot.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `slot` string · nullable  
        The starting slot (starters only).
      - `empty` boolean  
        An empty starting slot.
      - `points` number · nullable  
        His points this week as the platform shows them, live through games.
      - `projected` number · nullable  
        Kelly's mean projection for the week in the league's scoring; 0 on a bye; null when Kelly doesn't project him.
      - `opponent` string · nullable  
        His NFL opponent this week, or BYE.
      - `position_rank` string · nullable  
        His rank by that projection among every projected player at his position, e.g. WR9.
  - `matchup` object · nullable  
    This week's matchup; null on a bye. p_win, projected and its range are Kelly's when it has projections for the week.
    - `week` integer  
      The week.
    - `points` number · nullable  
      The team's points so far, as the platform shows them.
    - `p_win` number · nullable  
      Kelly's chance the team wins.  
      min 0 · max 1
    - `projected` number · nullable  
      Kelly's median final points.
    - `result` string · nullable  
      A finished week's result for the team: W, L or T.  
      One of: `W`, `L`, `T` (open: new values may be added).
    - `opponent` object · nullable  
      The opponent, with its points and projected points.
      - `team_id` string · nullable  
        The team's ID in the league.
      - `name` string · nullable  
        The team's name.
      - `manager` string · nullable  
        Its manager's name on the platform.
      - `yours` boolean  
        The person's own team.
  - `habits` object  
    How the manager runs the team this season.
    - `moves` integer  
      Adds by waiver claim or free agency.
    - `trades` integer  
      Trades made.
    - `claims_failed` integer  
      Waiver claims that failed.
    - `faab_spent` integer · nullable  
      FAAB spent.
    - `faab_left` integer · nullable  
      FAAB left.
    - `faab_budget` integer · nullable  
      The season's FAAB budget.
    - `waiver_position` integer · nullable  
      Its waiver order.
  - `moves` array of object  
    The team's latest moves, newest first (get_league_activity with team has the rest).
    - `id` string  
      The platform's ID for the move.
    - `type` string · nullable  
      waiver, free_agent, trade or commissioner.
    - `type_words` string  
      The kind of move in words.
    - `status` string · nullable  
      complete, failed or pending, as the platform says.
    - `week` integer · nullable  
      The week it happened in.
    - `at` string · nullable  
      When it happened.  
      format date-time
    - `teams` array of object  
      The teams in it.
      - `team_id` string · nullable  
        The team's ID in the league.
      - `name` string · nullable  
        The team's name.
      - `manager` string · nullable  
        Its manager's name on the platform.
      - `yours` boolean  
        The person's own team.
    - `adds` array of object  
      Players added.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `fantasy_team` object · nullable  
        The fantasy team he went to or left.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `drops` array of object  
      Players dropped.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `fantasy_team` object · nullable  
        The fantasy team he went to or left.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `bid` integer · nullable  
      The FAAB bid on a waiver claim.
    - `picks` array of object  
      Draft picks traded.
      - `season` string | integer · nullable  
        The pick's season.
      - `round` integer · nullable  
        Its round.
      - `from` object · nullable  
        The team that gave it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `to` object · nullable  
        The team that got it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `faab` array of object  
      FAAB traded.
      - `from` object · nullable  
        The team that sent it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `to` object · nullable  
        The team that got it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `amount` integer · nullable  
        Dollars.
  - `moves_count` integer  
    All of the team's moves this season.
  - `lineup` object · nullable  
    For the person's own team: Kelly's lineup check, as get_league's lineup. Null for any other team, another week or without projections.
  - `betting_angles` object  
    This week's game and prop lines for the team's starters (ADR-K480, ADR-K504): off unless the person turned the setting on or the call set angles to true; off, only on and setting.
    - `on` boolean  
      Whether the game lines are here.
    - `setting` boolean  
      The person's betting angles setting (default off).
    - `week` integer  
      The NFL week of the lines.
    - `games` array of object  
      One game per NFL team with a starter; empty when Kelly has no lines for the week.
      - `team` string  
        The starters' NFL team.
      - `opponent` string  
        Its opponent.
      - `home` boolean  
        Whether it plays at home.
      - `spread` number  
        Its spread, the books' consensus; minus is favoured.
      - `total` number  
        The game's total, the books' consensus.
      - `implied_points` number  
        Its points the spread and total imply.
      - `books` integer  
        Books in the consensus.
    - `props` array of object  
      Each starter's main prop lines in their next game, at Kelly's consensus (ADR-K504), in roster order; no edge status, nothing ranked.
      - `player_id` string  
        The starter's Kelly player ID.
      - `name` string · nullable  
        The starter's name.
      - `position` string · nullable  
        Their position.
      - `game_id` string · nullable  
        The game the lines are for.
      - `lines` array of object  
        One row per market, in the catalogue's order.
        - `stat` string  
          The prop market type.
        - `line` number · nullable  
          The consensus line; null for a yes/no market.
        - `side` string  
          over, or yes.
        - `p` number  
          That side's chance: no-vig, or vig-in when vig_in is true.
        - `vig_in` boolean  
          True for a one-way market (an anytime scorer).
        - `implied_mean` number · nullable  
          For a count stat, the mean the market implies.
        - `books` integer · nullable  
          Books in the consensus.
    - `attribution` string · nullable  
      A credit the prices' source requires, else null.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/teams?team=Team%2099
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "team: no team in this league goes by that; use a team's name, its manager or its ID.",
  "param": "team",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_8e9b502995f962bcbd75776e",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_00000000000000000000/teams
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No league with that league_id is yours.",
  "param": "league_id",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_e6c503e1d8d6a679025fc777",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`GET /v1/leagues/{league_id}/waivers`

## Get your league's waiver wire
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_league_waivers` · status live

The free agents in one of your connected leagues, best first by Kelly's value for your team, each with its points this week and for the rest of the season, the starter it would replace, the FAAB bid and its range and chance to win, and the rivals likeliest to bid; with every team's FAAB left and waiver order. Pages by cursor. Read only. Needs your own key or an OAuth token with read:league. Value, bids and rivals are Kelly's, from its projections.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

- `position` string · query  
  Only this position.  
  One of: `QB`, `RB`, `WR`, `TE`, `K`, `DEF`, `DST` (open: new values may be added).
- `scope` string · query  
  free_agents (the default), mine (your roster), rostered (every team's) or all.  
  One of: `free_agents`, `mine`, `rostered`, `all` (open: new values may be added).
- `sort` string · query  
  The column to sort by; rank (the default) is Kelly's order, best first.  
  One of: `rank`, `ros_points`, `points`, `last3`, `target_share`, `name` (open: new values may be added).
- `order` string · query  
  desc or asc; left out, highest first (name: A to Z).  
  One of: `desc`, `asc` (open: new values may be added).
- `q` string · query  
  Only players whose name holds every word of this, such as chase.  
  min length 1 · max length 40
- `cursor` string · query  
  next_cursor from the last page.  
  min length 1 · max length 512
- `limit` integer · query  
  Players per page; default 25.  
  min 1 · max 100

### Response
`200` A page of players.

- `object` const · required  
  Always league_waivers.  
  Always `"league_waivers"`.
- `league_waivers` object · required  
  The free agents in the person's league, one page at a time.
  - `league` object  
    The league and how old Kelly's copy is.
    - `id` string  
      The league's Kelly ID (lg_…).
    - `name` string  
      The league's name.
    - `platform` string  
      sleeper, yahoo, myfantasyleague, fleaflicker or paste.
    - `season` integer  
      The season.
    - `week` integer  
      The platform's current week.
    - `scoring` string · nullable  
      The scoring in words, such as Half-PPR · 12-team · 1QB.
    - `as_of` string · nullable  
      When Kelly last read the league from its platform.  
      format date-time
    - `age_s` integer · nullable  
      Seconds since then.
  - `faab` boolean  
    Whether the league bids FAAB.
  - `projected` boolean  
    False when Kelly has no projections for the week, so no free agent is ranked.
  - `position` string · nullable  
    The position asked for, if any.
  - `scope` string  
    free_agents, mine, rostered or all (ADR-K505).
  - `sort` string  
    The column the players are sorted by; rank is Kelly's order.
  - `order` string  
    desc or asc.
  - `q` string · nullable  
    The name search the page answers (P12); null for every player.
  - `count` integer  
    Players in the list across every page.
  - `players` array of object  
    This page of players in the sort asked for. A free agent is as get_league's free_agents: player_id, name, position, team, rank, value, points, ros_points, replaces, bid, bid_low, bid_high, p_win, bidders, rivals; a rostered player adds fantasy_team and has null waiver fields. Every row adds last3, target_share and opponent.
    - `player_id` string  
      Kelly's player ID.
    - `name` string · nullable  
      The player's name.
    - `position` string · nullable  
      His position.
    - `team` string · nullable  
      His NFL team.
    - `fantasy_team` object · nullable  
      The league team that rosters him; null for a free agent.
    - `ros_points` number · nullable  
      Kelly's rest-of-season points, league scoring.
    - `points` number · nullable  
      Kelly's projection this week, league scoring.
    - `last3` number · nullable  
      His average points over his last three games, scored the league's way.
    - `target_share` number · nullable  
      His average share of his team's targets over those games; null when none is recorded.
    - `opponent` string · nullable  
      His NFL opponent this week, or BYE.
  - `next_cursor` string · nullable  
    Pass it as cursor for the next page; null on the last.
  - `teams` array of object  
    Every team's FAAB left and waiver order, first in line first.
    - `team_id` string  
      The team's ID.
    - `name` string · nullable  
      Its name.
    - `manager` string · nullable  
      Its manager.
    - `yours` boolean  
      The person's own team.
    - `faab_left` integer · nullable  
      FAAB left.
    - `waiver_position` integer · nullable  
      Waiver order.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/waivers?position=LB
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "position: String should match pattern '^(QB|RB|WR|TE|K|DEF|DST)$'",
  "param": "position",
  "doc_url": "https://docs.askkelly.ai/problems/invalid_request",
  "request_id": "req_1d2109e7cd4e188de6aa11f7",
  "retryable": false,
  "display_message": "Something in that request was not understood."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_00000000000000000000/waivers
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No league with that league_id is yours.",
  "param": "league_id",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_12ffa6c7938089bafb0d89a6",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`GET /v1/leagues/{league_id}/activity`

## Get your league's activity
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_league_activity` · status live

The moves in one of your connected leagues this season, newest first: waiver claims won and failed with their bids, free-agent pickups, drops and trades with picks and FAAB; one team's when `team` is given. Pages by cursor. Read only. Needs your own key or an OAuth token with read:league. The platform's own record of the league's moves.

### Parameters
- `league_id` string · path · required  
  The league's Kelly ID (lg_), from list_leagues.  
  pattern ^lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}$

- `team` string · query  
  Only this team's moves: its name, manager or team ID.  
  min length 1 · max length 100
- `cursor` string · query  
  next_cursor from the last page.  
  min length 1 · max length 512
- `limit` integer · query  
  Moves per page; default 25.  
  min 1 · max 100

### Response
`200` A page of moves.

- `object` const · required  
  Always league_activity.  
  Always `"league_activity"`.
- `league_activity` object · required  
  The moves in the person's league this season, one page at a time.
  - `league` object  
    The league and how old Kelly's copy is.
    - `id` string  
      The league's Kelly ID (lg_…).
    - `name` string  
      The league's name.
    - `platform` string  
      sleeper, yahoo, myfantasyleague, fleaflicker or paste.
    - `season` integer  
      The season.
    - `week` integer  
      The platform's current week.
    - `scoring` string · nullable  
      The scoring in words, such as Half-PPR · 12-team · 1QB.
    - `as_of` string · nullable  
      When Kelly last read the league from its platform.  
      format date-time
    - `age_s` integer · nullable  
      Seconds since then.
  - `team` object · nullable  
    The team asked for; null for the whole league.
    - `team_id` string · nullable  
      The team's ID in the league.
    - `name` string · nullable  
      The team's name.
    - `manager` string · nullable  
      Its manager's name on the platform.
    - `yours` boolean  
      The person's own team.
  - `count` integer  
    Moves across every page.
  - `moves` array of object  
    This page of moves, newest first.
    - `id` string  
      The platform's ID for the move.
    - `type` string · nullable  
      waiver, free_agent, trade or commissioner.
    - `type_words` string  
      The kind of move in words.
    - `status` string · nullable  
      complete, failed or pending, as the platform says.
    - `week` integer · nullable  
      The week it happened in.
    - `at` string · nullable  
      When it happened.  
      format date-time
    - `teams` array of object  
      The teams in it.
      - `team_id` string · nullable  
        The team's ID in the league.
      - `name` string · nullable  
        The team's name.
      - `manager` string · nullable  
        Its manager's name on the platform.
      - `yours` boolean  
        The person's own team.
    - `adds` array of object  
      Players added.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `fantasy_team` object · nullable  
        The fantasy team he went to or left.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `drops` array of object  
      Players dropped.
      - `name` string · nullable  
        The player's name.
      - `position` string · nullable  
        His position.
      - `team` string · nullable  
        His NFL team.
      - `fantasy_team` object · nullable  
        The fantasy team he went to or left.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `bid` integer · nullable  
      The FAAB bid on a waiver claim.
    - `picks` array of object  
      Draft picks traded.
      - `season` string | integer · nullable  
        The pick's season.
      - `round` integer · nullable  
        Its round.
      - `from` object · nullable  
        The team that gave it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `to` object · nullable  
        The team that got it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
    - `faab` array of object  
      FAAB traded.
      - `from` object · nullable  
        The team that sent it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `to` object · nullable  
        The team that got it.
        - `team_id` string · nullable  
          The team's ID in the league.
        - `name` string · nullable  
          The team's name.
        - `manager` string · nullable  
          Its manager's name on the platform.
        - `yours` boolean  
          The person's own team.
      - `amount` integer · nullable  
        Dollars.
  - `next_cursor` string · nullable  
    Pass it as cursor for the next page; null on the last.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/activity
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_7aa58507097de468c21b19a4",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/activity?limit=3
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_activity",
  "league_activity": {
    "league": {
      "id": "lg_dzs55c9tr5hqqr0ja1tt",
      "name": "Kelly Synthetic League (Sleeper shape)",
      "platform": "sleeper",
      "season": 2026,
      "week": 3,
      "scoring": "PPR · 12-team · 1QB",
      "as_of": "2026-10-04T17:30:00+00:00",
      "age_s": 0
    },
    "team": null,
    "count": 29,
    "moves": [
      {
        "id": "900029",
        "type": "trade",
        "type_words": "trade",
        "status": "complete",
        "week": 2,
        "at": "2026-09-10T00:26:40.029000Z",
        "teams": [
          {
            "team_id": "3",
            "name": "Team 03",
            "manager": "owner03",
            "yours": false
          },
          {
            "team_id": "9",
            "name": "Team 09",
            "manager": "owner09",
            "yours": false
          }
        ],
        "adds": [
          {
            "name": "Julius Chestnut",
            "position": "RB",
            "team": "TEN",
            "fantasy_team": {
              "team_id": "9",
              "name": "Team 09",
              "manager": "owner09",
              "yours": false
            }
          },
          {
            "name": "Nick Westbrook-Ikhine",
            "position": "WR",
            "team": "IND",
            "fantasy_team": {
              "team_id": "3",
              "name": "Team 03",
              "manager": "owner03",
              "yours": false
            }
          }
        ],
        "drops": [
          {
            "name": "Julius Chestnut",
            "position": "RB",
            "team": "TEN",
            "fantasy_team": {
              "team_id": "3",
              "name": "Team 03",
              "manager": "owner03",
              "yours": false
            }
          },
          {
            "name": "Nick Westbrook-Ikhine",
            "position": "WR",
            "team": "IND",
            "fantasy_team": {
              "team_id": "9",
              "name": "Team 09",
              "manager": "owner09",
              "yours": false
            }
          }
        ],
        "bid": null,
        "picks": [
          {
            "season": "2027",
            "round": 3,
            "from": {
              "team_id": "3",
              "name": "Team 03",
              "manager": "owner03",
              "yours": false
            },
            "to": {
              "team_id": "9",
              "name": "Team 09",
              "manager": "owner09",
              "yours": false
            }
          }
        ],
        "faab": [
          {
            "from": {
              "team_id": "9",
              "name": "Team 09",
              "manager": "owner09",
              "yours": false
            },
            "to": {
              "team_id": "3",
              "name": "Team 03",
              "manager": "owner03",
              "yours": false
            },
            "amount": 5
          }
        ]
      },
      {
        "id": "900028",
        "type": "free_agent",
        "type_words": "free-agent pickup",
        "status": "complete",
        "week": 2,
        "at": "2026-09-10T00:26:40.028000Z",
        "teams": [
          {
            "team_id": "4",
            "name": "Team 04",
            "manager": "owner04",
            "yours": false
          }
        ],
        "adds": [
          {
            "name": "Dareke Young",
            "position": "WR",
            "team": "LV",
            "fantasy_team": {
              "team_id": "4",
              "name": "Team 04",
              "manager": "owner04",
              "yours": false
            }
          }
        ],
        "drops": [
          {
            "name": "Britain Covey",
            "position": "WR",
            "team": "PHI",
            "fantasy_team": {
              "team_id": "4",
              "name": "Team 04",
              "manager": "owner04",
              "yours": false
            }
          }
        ],
        "bid": null,
        "picks": [],
        "faab": []
      },
      {
        "id": "900027",
        "type": "waiver",
        "type_words": "waiver claim",
        "status": "complete",
        "week": 3,
        "at": "2026-09-10T00:26:40.027000Z",
        "teams": [
          {
            "team_id": "10",
            "name": "Team 10",
            "manager": "owner10",
            "yours": false
          }
        ],
        "adds": [
          {
            "name": "Jaylen Waddle",
            "position": "WR",
            "team": "DEN",
            "fantasy_team": {
              "team_id": "10",
              "name": "Team 10",
              "manager": "owner10",
              "yours": false
            }
          }
        ],
        "drops": [],
        "bid": 15,
        "picks": [],
        "faab": []
      }
    ],
    "next_cursor": "eyJ2IjoxLCJvIjozLCJmIjoiNjM2NjZjNzZhMmVjMjgwNSJ9"
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_448862a9211fb6f8f5e6f507"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/leagues/{league_id}/odds`

## Get a league's playoff odds
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_league_odds` · status live

Every team's chance to make the playoffs, get a first-round bye and win the title in a fantasy league (a Sleeper league ID, or one saved to your projects), from 10,000 seasons simulated by the league's own rules on Kelly's projections; your team's seeds, final wins and points still to score. The same facts as Kelly MCP's get_league_odds. Read only. Needs your own key or an OAuth token with read:league. Plays out the rest of a fantasy league's season 10,000 times on Kelly's projections, by the league's own playoff rules, and returns every team's chance to make the playoffs, get a bye and win the title. Read only: a Sleeper league ID is read live and kept nowhere.

### Parameters
- `league_id` string · path · required  
  One of your connected leagues (lg_, from list_leagues), or any Sleeper league ID.  
  pattern ^(?:lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}|[0-9]{8,25})$

- `team` string · query  
  Your team in it: its name, owner or roster number, when Kelly doesn't know it.  
  min length 1 · max length 100

### Response
`200` The league's playoff odds.

- `object` const · required  
  Always league_odds.  
  Always `"league_odds"`.
- `league_odds` object · required  
  The person's league's playoff odds.
  - `league` string  
    The league's name.
  - `week` integer  
    The league's current week.
  - `rules` string  
    The playoff rules the run used, in words: spots, byes, median game, divisions, tiebreaks, re-seeding, two-week rounds.
  - `playoff_spots` integer  
    Teams that make the playoffs.
  - `seasons_simulated` integer  
    Simulated seasons behind every chance.
  - `teams` array of object  
    Every team, most likely first.
    - `id` string  
      The team's roster ID in the league.
    - `name` string  
      The team's name in the league.
    - `record` string  
      Wins–losses(–ties), as the league shows it.
    - `points_for` number  
      Points for this season.
    - `p_playoffs` number  
      Chance to make the playoffs.  
      min 0 · max 1
    - `expected_seed` number  
      Mean final seed (1 is best).
    - `p_bye` number  
      Chance of a first-round bye; absent when the bracket has none.  
      min 0 · max 1
    - `p_title` number  
      Chance to win the title; absent once the playoffs have started.  
      min 0 · max 1
    - `p_division` number  
      Chance to win its division; leagues with divisions.  
      min 0 · max 1
    - `expected_wins` number  
      Mean final wins (ties and median games count).
    - `wins_low` number  
      Final wins, 10th percentile.
    - `wins_high` number  
      Final wins, 90th percentile.
    - `p_last` number  
      Chance of finishing last.  
      min 0 · max 1
    - `clinched` boolean  
      Present and true when a proof says the team is in under every result left.
    - `eliminated` boolean  
      Present and true when a proof says the team is out under every result left.
    - `yours` boolean  
      The person's own team.
  - `your_team` object · nullable  
    The person's team; null when unknown.
    - `id` string  
      Its roster ID.
    - `name` string  
      Its name.
    - `record` string  
      Its record.
    - `points_for` number  
      Points for.
    - `place_now` integer  
      Its place in the standings now.
    - `p_playoffs` number  
      Chance to make the playoffs.  
      min 0 · max 1
    - `p_bye` number  
      Chance of a first-round bye.  
      min 0 · max 1
    - `p_title` number  
      Chance to win the title.  
      min 0 · max 1
    - `p_top_seed` number  
      Chance of the top seed.  
      min 0 · max 1
    - `p_last` number  
      Chance of finishing last.  
      min 0 · max 1
    - `p_division` number  
      Chance to win its division.  
      min 0 · max 1
    - `expected_seed` number  
      Mean final seed.
    - `expected_wins` number  
      Mean final wins.
    - `wins_low` number  
      Final wins, 10th percentile.
    - `wins_high` number  
      Final wins, 90th percentile.
    - `points_still_to_score` number  
      Projected points in the regular season left.
    - `p_seeds` array of number  
      Chance of each final seed, seed 1 first.
    - `starters_on_bye_in_playoff_weeks` array of string  
      Its players on an NFL bye in a fantasy playoff week.
    - `clinched` string  
      A proof's result: in under every result left even losing every tiebreak, or "not yet".
    - `eliminated` string  
      A proof's result: out under every result left even winning every tiebreak.
    - `clinched_bye` string  
      A proof's result for the first-round bye.
    - `p_playoffs_margin` number  
      The simulation's 95% margin on p_playoffs (1.96·√(p(1−p)/seasons)).  
      min 0 · max 1
    - `p_playoffs_by_week` array of object  
      The team's playoff chance as Kelly first published it each earlier week this season, then now; absent before a second week is logged.
      - `week` integer  
        The week.
      - `p_playoffs` number  
        The playoff chance that week.  
        min 0 · max 1
    - `this_week` object  
      This week's game: the opponent, the chance to win it, and the playoff chance after a win and after a loss (p_swing is the difference).
      - `week` integer  
        The week.
      - `opponent` string  
        The opponent's name.
      - `p_win_game` number  
        Chance to win the game.  
        min 0 · max 1
      - `p_playoffs_if_win` number  
        Playoff chance after a win.  
        min 0 · max 1
      - `p_playoffs_if_loss` number  
        Playoff chance after a loss.  
        min 0 · max 1
      - `p_swing` number  
        The playoff chance the game is worth.  
        min 0 · max 1
    - `root_for` array of object  
      The other games this week that move the team's playoff chance most: the side to root for, the chance if it wins and if it loses, and p_swing.
      - `team` string  
        The side to root for.
      - `against` string  
        Its opponent.
      - `p_playoffs_if_they_win` number  
        Playoff chance if it wins.  
        min 0 · max 1
      - `p_playoffs_if_they_lose` number  
        Playoff chance if it loses.  
        min 0 · max 1
      - `p_swing` number  
        The difference.  
        min 0 · max 1
    - `wins_needed` object  
      Wins still to play for (head-to-head and median games), the fewest that give even and 90% odds, and the playoff chance for each count.
      - `games_left` number  
        Games left, median games included.
      - `for_even_odds` number · nullable  
        Fewest more wins for at least 50%.
      - `for_90_percent` number · nullable  
        Fewest more wins for at least 90%.
      - `by_wins` array of object  
        The playoff chance for each count of more wins.
        - `more_wins` number  
          Wins still to take, from now.
        - `p_playoffs` number  
          Playoff chance with that many.  
          min 0 · max 1
    - `points_for_tiebreak` object  
      How often a tie on wins at the cutoff decides the team's fate (points for, then points against), and its chance when it does.
      - `p_decides_it` number  
        Share of seasons decided by the tiebreak.  
        min 0 · max 1
      - `p_playoffs_when_it_does` number  
        Playoff chance in those seasons.  
        min 0 · max 1
    - `settles_this_week` object  
      What this week's results settle (P7): each way is a proof under every result after it, whatever the points; absent when nothing this week settles it or more than 12 games follow.
      - `clinches_a_spot_if` object  
        The ways it clinches a playoff spot this week.
        - `ways` array of string  
          Each way in words: the results this week that are enough on their own.
        - `every_way` boolean  
          Whether the ways listed are every result this week that does it.
      - `clinches_a_bye_if` object  
        The ways it clinches a first-round bye this week.
        - `ways` array of string  
          Each way in words: the results this week that are enough on their own.
        - `every_way` boolean  
          Whether the ways listed are every result this week that does it.
      - `is_out_if` object  
        The ways it is knocked out this week.
        - `ways` array of string  
          Each way in words: the results this week that are enough on their own.
        - `every_way` boolean  
          Whether the ways listed are every result this week that does it.
    - `bracket_path` array of object  
      Each playoff round: the chance to play in it and the likeliest opponents, with the chance of meeting each.
      - `round` string  
        The round.
      - `p_play` number  
        Chance to play in it.  
        min 0 · max 1
      - `likely_opponents` array of object  
        The likeliest opponents.
        - `name` string  
          The opponent.
        - `p_meet` number  
          Chance of meeting it there.  
          min 0 · max 1
  - `note` string  
    Present when Kelly doesn't know the person's team.
  - `method_notes` array of string  
    Assumptions the run made, in words.
  - `title_odds` string  
    Why title odds are absent, when they are.
  - `model` string  
    The shared errors the run drew, in words, when it drew them.
  - `calibration` string  
    "calibrating" until the odds pass a backtest on finished seasons.
  - `biggest_games_this_week` array of object  
    This week's games that move the league's playoff chances most: p_moved is the share of playoff chances that change hands with the result.
    - `game` string  
      The two teams.
    - `p_moved` number  
      Playoff chances that change hands.  
      min 0 · max 1
  - `settles_this_week` array of object  
    Every team whose race this week's results can settle: its name and the ways (P7).
    - `team` string  
      The team.
    - `clinches_a_spot_if` object  
      The ways it clinches a playoff spot this week.
      - `ways` array of string  
        Each way in words: the results this week that are enough on their own.
      - `every_way` boolean  
        Whether the ways listed are every result this week that does it.
    - `clinches_a_bye_if` object  
      The ways it clinches a first-round bye this week.
      - `ways` array of string  
        Each way in words: the results this week that are enough on their own.
      - `every_way` boolean  
        Whether the ways listed are every result this week that does it.
    - `is_out_if` object  
      The ways it is knocked out this week.
      - `ways` array of string  
        Each way in words: the results this week that are enough on their own.
      - `every_way` boolean  
        Whether the ways listed are every result this week that does it.
  - `playoff_bracket` array of object  
    The bracket (P7): the host's winners bracket then its consolation bracket or toilet bowl once the playoffs start, else the projected winners bracket.
    - `kind` string  
      The playoff bracket, the consolation bracket or the toilet bowl, in words.
    - `projected` boolean  
      True before the playoffs: today's likeliest seeds, not the host's bracket.
    - `first_round` object  
      Projected only: the first round.
      - `weeks` array of integer  
        Its weeks.
      - `games` array of array  
        Its games, two seeded teams each.
      - `byes` array of object  
        The seeds on a first-round bye.
        - `seed` integer  
          Its seed on today's likeliest standings.
        - `team` string  
          Its name.
        - `projected_points` number · nullable  
          Kelly's projection for the first playoff week.
    - `later_round_weeks` array of array  
      Projected only: each later round's weeks.
    - `rounds` array of object  
      The host's bracket only: each round with its weeks, games and byes.
      - `round` integer  
        The round, first is 1.
      - `weeks` array of integer  
        Its weeks.
      - `games` array of object  
        Its games.
        - `teams` array of object  
          The two teams.
          - `team` string · nullable  
            Its name; null while the host hasn't filled the slot.
          - `points` number · nullable  
            Its points for the round's weeks, from the synced matchups.
        - `winner` string · nullable  
          The winner once decided.
        - `for_place` integer  
          The place the game decides, where it decides one.
      - `byes` array of object  
        Teams on a bye that round, with their points that week.
        - `team` string · nullable  
          Its name; null while the host hasn't filled the slot.
        - `points` number · nullable  
          Its points for the round's weeks, from the synced matchups.
  - `leagues` array of object  
    With several connected leagues and none named: each league's ID, name and platform, to call again with.
    - `league_id` string  
      Its Kelly league ID, to call again with.
    - `name` string  
      Its name.
    - `platform` string  
      Where it's hosted.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/1200000000000000001/odds
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_53b4e82e8bd91b9a5a569c4d",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/1200000000000000001/odds?team=Team%2007
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_odds",
  "league_odds": {
    "league": "Kelly Synthetic League (Sleeper shape)",
    "week": 3,
    "rules": "6 of 12 teams make the playoffs, starting week 15; the top 2 get a first-round bye; ties in the standings go to points for, then points against.",
    "playoff_spots": 6,
    "seasons_simulated": 10000,
    "teams": [
      {
        "id": "6",
        "name": "Team 06",
        "record": "0–2",
        "points_for": 200.8,
        "p_playoffs": 0.7008,
        "expected_seed": 4.88,
        "expected_wins": 7.88,
        "wins_low": 5,
        "wins_high": 10,
        "p_last": 0.0187,
        "p_bye": 0.2825,
        "p_title": 0.1766
      },
      {
        "id": "1",
        "name": "Team 01",
        "record": "1–1",
        "points_for": 192.3,
        "p_playoffs": 0.698,
        "expected_seed": 4.95,
        "expected_wins": 8.07,
        "wins_low": 5,
        "wins_high": 11,
        "p_last": 0.0191,
        "p_bye": 0.2639,
        "p_title": 0.1348
      },
      {
        "id": "2",
        "name": "Team 02",
        "record": "2–0",
        "points_for": 218.6,
        "p_playoffs": 0.694,
        "expected_seed": 4.91,
        "expected_wins": 8.2,
        "wins_low": 5,
        "wins_high": 11,
        "p_last": 0.014,
        "p_bye": 0.2775,
        "p_title": 0.1039
      },
      {
        "id": "12",
        "name": "Team 12",
        "record": "0–2",
        "points_for": 173.6,
        "p_playoffs": 0.6871,
        "expected_seed": 5.05,
        "expected_wins": 7.82,
        "wins_low": 5,
        "wins_high": 10,
        "p_last": 0.0217,
        "p_bye": 0.2566,
        "p_title": 0.1704
      },
      {
        "id": "7",
        "name": "Team 07",
        "record": "1–1",
        "points_for": 227.1,
        "p_playoffs": 0.669,
        "expected_seed": 5.09,
        "expected_wins": 7.83,
        "wins_low": 5,
        "wins_high": 10,
        "p_last": 0.0172,
        "p_bye": 0.2603,
        "p_title": 0.1327,
        "yours": true
      },
      {
        "id": "9",
        "name": "Team 09",
        "record": "2–0",
        "points_for": 218.7,
        "p_playoffs": 0.6006,
        "expected_seed": 5.64,
        "expected_wins": 7.78,
        "wins_low": 5,
        "wins_high": 11,
        "p_last": 0.0236,
        "p_bye": 0.2034,
        "p_title": 0.0646
      },
      {
        "id": "8",
        "name": "Team 08",
        "record": "1–1",
        "points_for": 192.4,
        "p_playoffs": 0.5719,
        "expected_seed": 5.89,
        "expected_wins": 7.46,
        "wins_low": 5,
        "wins_high": 10,
        "p_last": 0.0379,
        "p_bye": 0.1798,
        "p_title": 0.0876
      },
      {
        "id": "10",
        "name": "Team 10",
        "record": "2–0",
        "points_for": 182,
        "p_playoffs": 0.4252,
        "expected_seed": 7.01,
        "expected_wins": 6.96,
        "wins_low": 4,
        "wins_high": 10,
        "p_last": 0.0637,
        "p_bye": 0.1009,
        "p_title": 0.0353
      },
      {
        "id": "3",
        "name": "Team 03",
        "record": "1–1",
        "points_for": 183.9,
        "p_playoffs": 0.4056,
        "expected_seed": 7.14,
        "expected_wins": 6.64,
        "wins_low": 4,
        "wins_high": 9,
        "p_last": 0.0729,
        "p_bye": 0.0973,
        "p_title": 0.047
      },
      {
        "id": "4",
        "name": "Team 04",
        "record": "1–1",
        "points_for": 210.2,
        "p_playoffs": 0.2752,
        "expected_seed": 8.19,
        "expected_wins": 5.85,
        "wins_low": 3,
        "wins_high": 9,
        "p_last": 0.1213,
        "p_bye": 0.0505,
        "p_title": 0.027
      },
      {
        "id": "5",
        "name": "Team 05",
        "record": "1–1",
        "points_for": 174.5,
        "p_playoffs": 0.1715,
        "expected_seed": 9.23,
        "expected_wins": 5.25,
        "wins_low": 3,
        "wins_high": 8,
        "p_last": 0.2268,
        "p_bye": 0.0194,
        "p_title": 0.012
      },
      {
        "id": "11",
        "name": "Team 11",
        "record": "0–2",
        "points_for": 208.3,
        "p_playoffs": 0.1011,
        "expected_seed": 10.03,
        "expected_wins": 4.24,
        "wins_low": 2,
        "wins_high": 7,
        "p_last": 0.3631,
        "p_bye": 0.0079,
        "p_title": 0.0081
      }
    ],
    "model": "Each player's season-long form, each NFL game's shared swing and injury spells that last weeks are drawn too, fitted on the 2019–2025 seasons.",
    "calibration": "calibrating: these odds haven't yet been checked against finished fantasy seasons (Jon's plan, call 4: the chip stays until the backtest passes)",
    "your_team": {
      "id": "7",
      "name": "Team 07",
      "record": "1–1",
      "points_for": 227.1,
      "place_now": 4,
      "p_playoffs": 0.669,
      "p_top_seed": 0.1384,
      "p_last": 0.0172,
      "expected_seed": 5.09,
      "expected_wins": 7.83,
      "wins_low": 5,
      "wins_high": 10,
      "points_still_to_score": 1141.1,
      "p_seeds": [
        0.1384,
        0.1219,
        0.1178,
        0.0989,
        0.1045,
        0.0875,
        0.0846,
        0.0759,
        0.0643,
        0.0543,
        0.0347,
        0.0172
      ],
      "p_bye": 0.2603,
      "p_title": 0.1327,
      "clinched": "not yet",
      "p_playoffs_margin": 0.0092,
      "this_week": {
        "week": 3,
        "opponent": "Team 10",
        "p_win_game": 0.6948,
        "p_playoffs_if_win": 0.7143,
        "p_playoffs_if_loss": 0.5659,
        "p_swing": 0.1484
      },
      "root_for": [
        {
          "team": "Team 09",
          "against": "Team 08",
          "p_playoffs_if_they_win": 0.6827,
          "p_playoffs_if_they_lose": 0.6584,
          "p_swing": 0.0243
        },
        {
          "team": "Team 01",
          "against": "Team 03",
          "p_playoffs_if_they_win": 0.6754,
          "p_playoffs_if_they_lose": 0.6584,
          "p_swing": 0.0171
        },
        {
          "team": "Team 05",
          "against": "Team 12",
          "p_playoffs_if_they_win": 0.6786,
          "p_playoffs_if_they_lose": 0.6665,
          "p_swing": 0.0121
        },
        {
          "team": "Team 11",
          "against": "Team 06",
          "p_playoffs_if_they_win": 0.6746,
          "p_playoffs_if_they_lose": 0.6675,
          "p_swing": 0.0071
        }
      ],
      "wins_needed": {
        "games_left": 12,
        "for_even_odds": 6,
        "for_90_percent": 7,
        "by_wins": [
          {
            "more_wins": 2,
            "p_playoffs": 0.001
          },
          {
            "more_wins": 3,
            "p_playoffs": 0.001
          },
          {
            "more_wins": 4,
            "p_playoffs": 0.001
          },
          {
            "more_wins": 5,
            "p_playoffs": 0.0431
          },
          {
            "more_wins": 6,
            "p_playoffs": 0.5949
          },
          {
            "more_wins": 7,
            "p_playoffs": 0.9789
          },
          {
            "more_wins": 8,
            "p_playoffs": 0.999
          },
          {
            "more_wins": 9,
            "p_playoffs": 0.999
          },
          {
            "more_wins": 10,
            "p_playoffs": 0.999
          },
          {
            "more_wins": 11,
            "p_playoffs": 0.999
          }
        ]
      },
      "points_for_tiebreak": {
        "p_decides_it": 0.1525,
        "p_playoffs_when_it_does": 0.7075
      },
      "bracket_path": [
        {
          "round": "quarterfinal",
          "p_play": 0.4087,
          "likely_opponents": [
            {
              "name": "Team 12",
              "p_meet": 0.0521
            },
            {
              "name": "Team 06",
              "p_meet": 0.05
            },
            {
              "name": "Team 01",
              "p_meet": 0.0476
            }
          ]
        },
        {
          "round": "semifinal",
          "p_play": 0.4802,
          "likely_opponents": [
            {
              "name": "Team 01",
              "p_meet": 0.0731
            },
            {
              "name": "Team 06",
              "p_meet": 0.072
            },
            {
              "name": "Team 02",
              "p_meet": 0.0664
            }
          ]
        },
        {
          "round": "final",
          "p_play": 0.2553,
          "likely_opponents": [
            {
              "name": "Team 06",
              "p_meet": 0.0486
            },
            {
              "name": "Team 12",
              "p_meet": 0.0451
            },
            {
              "name": "Team 02",
              "p_meet": 0.0369
            }
          ]
        }
      ]
    },
    "biggest_games_this_week": [
      {
        "game": "Team 08 vs Team 09",
        "p_moved": 0.2276
      },
      {
        "game": "Team 04 vs Team 02",
        "p_moved": 0.1932
      },
      {
        "game": "Team 07 vs Team 10",
        "p_moved": 0.192
      }
    ],
    "playoff_bracket": [
      {
        "kind": "the playoff bracket",
        "projected": true,
        "first_round": {
          "weeks": [
            15
          ],
          "games": [
            [
              {
                "seed": 4,
                "team": "Team 12",
                "projected_points": 93.7
              },
              {
                "seed": 5,
                "team": "Team 07",
                "projected_points": 89
              }
            ],
            [
              {
                "seed": 3,
                "team": "Team 01",
                "projected_points": 88.5
              },
              {
                "seed": 6,
                "team": "Team 09",
                "projected_points": 80.5
              }
            ]
          ],
          "byes": [
            {
              "seed": 1,
              "team": "Team 06",
              "projected_points": 93.8
            },
            {
              "seed": 2,
              "team": "Team 02",
              "projected_points": 84.6
            }
          ]
        },
        "later_round_weeks": [
          [
            16
          ],
          [
            17
          ]
        ]
      }
    ],
    "method_notes": [
      "no league schedule for weeks 5–14: deterministic round-robin pairings assumed"
    ]
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_e0f0ce2d712e4f10953e04e6"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/leagues/{league_id}/analysis`

## Analyze a league
scope `read:league` · 0 credits, not charged during the beta · MCP tool `analyze_league` · status live

One analysis of a fantasy league from its final weeks, for every team with yours picked out: points left on the bench (lineups), schedule luck (luck), strength of schedule (schedule), what each pickup has scored (pickups) or who is winning each trade (trades). Needs your own key or an OAuth token with read:league. Read only: a Sleeper league ID is read live and kept nowhere.

### Parameters
- `league_id` string · path · required  
  One of your connected leagues (lg_, from list_leagues), or any Sleeper league ID.  
  pattern ^(?:lg_[0123456789abcdefghjkmnpqrstvwxyz]{20}|[0-9]{8,25})$

- `analysis` string · query · required  
  Which analysis: lineups, luck, schedule, pickups or trades.  
  One of: `lineups`, `luck`, `schedule`, `pickups`, `trades`, `skill`, `rules`, `playoff_size`, `bench_size`, `scoring`, `exposure`, `opposing_interests`, `sweat`, `same_player`, `veto_standard`, `prize_equity`, `payout_splits`, `draft`, `draft_rosters`, `draft_order`, `history`, `meetings`, `roster_rules`, `managers`, `rivalries`, `draft_habits`, `trending`, `keepers`, `rookie_draft`, `standings`, `habits`, `luck_table`, `power`, `predicted_picks`, `draft_power`, `faab`, `drops`, `trade_network`, `trade_backs`, `commissioner_moves`, `failed_claims`, `ownership_trail`, `median_game`, `waiver_setup`, `awards`, `ties`, `age_profile`, `roster_build`, `coach_rating`, `foresight`, `projection_performance`, `ranking_movement`, `composite_power`, `draft_assistant`, `rosters`, `trade_check`, `trade_offers`, `trade_finder`, `weekly_recap`, `team_names`, `trash_talk`, `house_rules`, `traded_picks`, `wrapped` (open: new values may be added).
- `team` string · query  
  Your team in it: its name, manager or roster number, when Kelly doesn't know it.  
  min length 1 · max length 100

### Response
`200` The analysis.

- `object` const · required  
  Always league_analysis.  
  Always `"league_analysis"`.
- `league_analysis` object · required  
  One analysis of the person's league.
  - `analysis` string  
    The analysis run.  
    One of: `lineups`, `luck`, `schedule`, `pickups`, `trades`, `skill`, `rules`, `playoff_size`, `bench_size`, `scoring`, `exposure`, `opposing_interests`, `sweat`, `same_player`, `veto_standard`, `prize_equity`, `payout_splits`, `draft`, `draft_rosters`, `draft_order`, `history`, `meetings`, `roster_rules`, `managers`, `rivalries`, `draft_habits`, `trending`, `keepers`, `rookie_draft`, `standings`, `habits`, `luck_table`, `power`, `predicted_picks`, `draft_power`, `faab`, `drops`, `trade_network`, `trade_backs`, `commissioner_moves`, `failed_claims`, `ownership_trail`, `median_game`, `waiver_setup`, `awards`, `ties`, `age_profile`, `roster_build`, `coach_rating`, `foresight`, `projection_performance`, `ranking_movement`, `composite_power`, `draft_assistant`, `rosters`, `trade_check`, `trade_offers`, `trade_finder`, `weekly_recap`, `team_names`, `trash_talk`, `house_rules`, `traded_picks`, `wrapped` (open: new values may be added).
  - `about` string  
    What it measures, in words.
  - `league` object · nullable  
    The league: id (lg_ or null when read live), name, platform, platform_league_id, season, week and the person's team.
  - `your_team_id` string · nullable  
    The person's team ID; null when Kelly doesn't know it.
  - `available` boolean  
    False when the league's platform lacks the data this analysis needs.
  - `reason` string · nullable  
    Why it isn't available.
  - `weeks` array of integer  
    The final weeks counted.
  - `result` object  
    The analysis for every team: `teams` rows (team_id, team, the measures and a rank) and, by analysis, `pickups`, `trades`, `record_under` or `random_schedules`. Shares are 0 to 1.
  - `yours` object | array · nullable  
    The person's row, pickups or trades.
- `as_of` string · required  
  When the value was true; for a derived value, its newest input's time.  
  format date-time
- `source` string · required  
  Who produced the value, as shown to readers.  
  min length 1
- `request_id` string · nullable  
  The request that produced this response.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`quota_exhausted`](/problems/quota_exhausted) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/analysis?analysis=luck
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the read:league scope.",
  "param": "read:league",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_b1b71d8629bffc06fec32017",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/analysis?analysis=lineups
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_analysis",
  "league_analysis": {
    "analysis": "lineups",
    "about": "points left on the bench: each week's best possible lineup in hindsight against the one started, bench points, lineup efficiency and the losses the bench cost",
    "league": {
      "id": "lg_dzs55c9tr5hqqr0ja1tt",
      "name": "Kelly Synthetic League (Sleeper shape)",
      "platform": "Sleeper",
      "platform_league_id": "1200000000000000001",
      "season": 2026,
      "week": 3,
      "your_team": "Team 07"
    },
    "your_team_id": "7",
    "available": true,
    "reason": null,
    "weeks": [
      1,
      2
    ],
    "result": {
      "teams": [
        {
          "team_id": "7",
          "team": "Team 07",
          "manager": "owner07",
          "actual_points": 227.1,
          "optimal_points": 306.01,
          "points_left": 78.91,
          "bench_points": 180.4,
          "efficiency_rate": 0.7421,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 129.7,
              "optimal": 164.08,
              "left": 34.38,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Josh Palmer",
                  "points": 23.8
                },
                {
                  "player": "Tanner Hudson",
                  "points": 20.1
                },
                {
                  "player": "Breece Hall",
                  "points": 9
                }
              ],
              "opponent_points": 116.6,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 97.4,
              "optimal": 141.93,
              "left": 44.53,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Tanner Hudson",
                  "points": 25.4
                },
                {
                  "player": "Rashod Bateman",
                  "points": 21.7
                },
                {
                  "player": "Deebo Samuel Sr.",
                  "points": 18
                },
                {
                  "player": "Joshua Dobbs",
                  "points": 10.6
                }
              ],
              "opponent_points": 110.6,
              "lost_to_bench": true
            }
          ],
          "rank": 1
        },
        {
          "team_id": "9",
          "team": "Team 09",
          "manager": "owner09",
          "actual_points": 218.7,
          "optimal_points": 296.97,
          "points_left": 78.27,
          "bench_points": 180.4,
          "efficiency_rate": 0.7364,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 0,
          "weeks": [
            {
              "week": 1,
              "actual": 94.9,
              "optimal": 137.08,
              "left": 42.18,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Dareke Young",
                  "points": 23.8
                },
                {
                  "player": "Durham Smythe",
                  "points": 20.1
                },
                {
                  "player": "Jaylen Waddle",
                  "points": 16.4
                },
                {
                  "player": "Keaton Mitchell",
                  "points": 9
                }
              ],
              "opponent_points": 90.4,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 123.8,
              "optimal": 159.89,
              "left": 36.09,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Durham Smythe",
                  "points": 25.4
                },
                {
                  "player": "Jaylen Waddle",
                  "points": 21.7
                },
                {
                  "player": "Nick Westbrook-Ikhine",
                  "points": 18
                },
                {
                  "player": "Mason Rudolph",
                  "points": 10.6
                }
              ],
              "opponent_points": 84.2,
              "lost_to_bench": false
            }
          ],
          "rank": 2
        },
        {
          "team_id": "2",
          "team": "Team 02",
          "manager": "owner02",
          "actual_points": 218.6,
          "optimal_points": 299.43,
          "points_left": 80.83,
          "bench_points": 180.4,
          "efficiency_rate": 0.7301,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 0,
          "weeks": [
            {
              "week": 1,
              "actual": 125.2,
              "optimal": 160.22,
              "left": 35.02,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Ben Skowronek",
                  "points": 23.8
                },
                {
                  "player": "Evan Engram",
                  "points": 20.1
                },
                {
                  "player": "Tyler Allgeier",
                  "points": 9
                }
              ],
              "opponent_points": 120.1,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 93.4,
              "optimal": 139.21,
              "left": 45.81,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Evan Engram",
                  "points": 25.4
                },
                {
                  "player": "Devin Duvernay",
                  "points": 21.7
                },
                {
                  "player": "Tom Kennedy",
                  "points": 18
                },
                {
                  "player": "Jacoby Brissett",
                  "points": 10.6
                }
              ],
              "opponent_points": 80.2,
              "lost_to_bench": false
            }
          ],
          "rank": 3
        },
        {
          "team_id": "4",
          "team": "Team 04",
          "manager": "owner04",
          "actual_points": 210.2,
          "optimal_points": 291.04,
          "points_left": 80.84,
          "bench_points": 180.4,
          "efficiency_rate": 0.7222,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 90.4,
              "optimal": 133.87,
              "left": 43.47,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "DeVonta Smith",
                  "points": 23.8
                },
                {
                  "player": "Dallas Goedert",
                  "points": 20.1
                },
                {
                  "player": "Jerry Jeudy",
                  "points": 16.4
                },
                {
                  "player": "Velus Jones Jr.",
                  "points": 9
                }
              ],
              "opponent_points": 94.9,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 119.8,
              "optimal": 157.17,
              "left": 37.37,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Dallas Goedert",
                  "points": 25.4
                },
                {
                  "player": "Jerry Jeudy",
                  "points": 21.7
                },
                {
                  "player": "DK Metcalf",
                  "points": 18
                },
                {
                  "player": "Cooper Rush",
                  "points": 10.6
                }
              ],
              "opponent_points": 88.2,
              "lost_to_bench": false
            }
          ],
          "rank": 4
        },
        {
          "team_id": "11",
          "team": "Team 11",
          "manager": "owner11",
          "actual_points": 208.3,
          "optimal_points": 291.7,
          "points_left": 83.4,
          "bench_points": 180.4,
          "efficiency_rate": 0.7141,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 2,
          "weeks": [
            {
              "week": 1,
              "actual": 120.1,
              "optimal": 155.84,
              "left": 35.74,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Kevin Austin Jr.",
                  "points": 23.8
                },
                {
                  "player": "Foster Moreau",
                  "points": 20.1
                },
                {
                  "player": "Ben VanSumeren",
                  "points": 9
                }
              ],
              "opponent_points": 125.2,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 88.2,
              "optimal": 135.86,
              "left": 47.66,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Foster Moreau",
                  "points": 25.4
                },
                {
                  "player": "Tylan Wallace",
                  "points": 21.7
                },
                {
                  "player": "Jauan Jennings",
                  "points": 18
                },
                {
                  "player": "Ben VanSumeren",
                  "points": 14.3
                },
                {
                  "player": "Baker Mayfield",
                  "points": 10.6
                }
              ],
              "opponent_points": 119.8,
              "lost_to_bench": true
            }
          ],
          "rank": 5
        },
        {
          "team_id": "6",
          "team": "Team 06",
          "manager": "owner06",
          "actual_points": 200.8,
          "optimal_points": 286.63,
          "points_left": 85.83,
          "bench_points": 180.4,
          "efficiency_rate": 0.7006,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 2,
          "weeks": [
            {
              "week": 1,
              "actual": 116.6,
              "optimal": 152.85,
              "left": 36.25,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Elijah Moore",
                  "points": 23.8
                },
                {
                  "player": "Dalton Schultz",
                  "points": 20.1
                },
                {
                  "player": "Kyren Williams",
                  "points": 9
                }
              ],
              "opponent_points": 129.7,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 84.2,
              "optimal": 133.78,
              "left": 49.58,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Dalton Schultz",
                  "points": 25.4
                },
                {
                  "player": "Chris Blair",
                  "points": 21.7
                },
                {
                  "player": "Marquise Brown",
                  "points": 18
                },
                {
                  "player": "Kyren Williams",
                  "points": 14.3
                },
                {
                  "player": "Patrick Mahomes",
                  "points": 10.6
                }
              ],
              "opponent_points": 123.8,
              "lost_to_bench": true
            }
          ],
          "rank": 6
        },
        {
          "team_id": "8",
          "team": "Team 08",
          "manager": "owner08",
          "actual_points": 192.4,
          "optimal_points": 278.64,
          "points_left": 86.24,
          "bench_points": 180.4,
          "efficiency_rate": 0.6905,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 81.8,
              "optimal": 127.73,
              "left": 45.93,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Bo Melton",
                  "points": 23.8
                },
                {
                  "player": "Mark Andrews",
                  "points": 20.1
                },
                {
                  "player": "Nico Collins",
                  "points": 16.4
                },
                {
                  "player": "Kenneth Walker III",
                  "points": 9
                }
              ],
              "opponent_points": 103.5,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 110.6,
              "optimal": 150.91,
              "left": 40.31,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Mark Andrews",
                  "points": 25.4
                },
                {
                  "player": "Nico Collins",
                  "points": 21.7
                },
                {
                  "player": "Cody White",
                  "points": 18
                },
                {
                  "player": "Kyle Allen",
                  "points": 10.6
                }
              ],
              "opponent_points": 97.4,
              "lost_to_bench": false
            }
          ],
          "rank": 7
        },
        {
          "team_id": "1",
          "team": "Team 01",
          "manager": "owner01",
          "actual_points": 192.3,
          "optimal_points": 281.08,
          "points_left": 88.78,
          "bench_points": 180.4,
          "efficiency_rate": 0.6841,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 112.1,
              "optimal": 149.38,
              "left": 37.28,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Tutu Atwell",
                  "points": 23.8
                },
                {
                  "player": "Jonnu Smith",
                  "points": 20.1
                },
                {
                  "player": "Justin Jefferson",
                  "points": 16.4
                },
                {
                  "player": "Rachaad White",
                  "points": 9
                }
              ],
              "opponent_points": 72.2,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 80.2,
              "optimal": 131.7,
              "left": 51.5,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Jonnu Smith",
                  "points": 25.4
                },
                {
                  "player": "Justin Jefferson",
                  "points": 21.7
                },
                {
                  "player": "Darius Slayton",
                  "points": 18
                },
                {
                  "player": "Rachaad White",
                  "points": 14.3
                },
                {
                  "player": "Jared Goff",
                  "points": 10.6
                }
              ],
              "opponent_points": 93.4,
              "lost_to_bench": true
            }
          ],
          "rank": 8
        },
        {
          "team_id": "3",
          "team": "Team 03",
          "manager": "owner03",
          "actual_points": 183.9,
          "optimal_points": 272.71,
          "points_left": 88.81,
          "bench_points": 180.4,
          "efficiency_rate": 0.6743,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 77.3,
              "optimal": 124.52,
              "left": 47.22,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Ja'Marr Chase",
                  "points": 23.8
                },
                {
                  "player": "Tyler Conklin",
                  "points": 20.1
                },
                {
                  "player": "CeeDee Lamb",
                  "points": 16.4
                },
                {
                  "player": "Julius Chestnut",
                  "points": 9
                }
              ],
              "opponent_points": 107,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 106.6,
              "optimal": 148.19,
              "left": 41.59,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Tyler Conklin",
                  "points": 25.4
                },
                {
                  "player": "CeeDee Lamb",
                  "points": 21.7
                },
                {
                  "player": "Alex Bachman",
                  "points": 18
                },
                {
                  "player": "Deshaun Watson",
                  "points": 10.6
                }
              ],
              "opponent_points": 101.4,
              "lost_to_bench": false
            }
          ],
          "rank": 9
        },
        {
          "team_id": "10",
          "team": "Team 10",
          "manager": "owner10",
          "actual_points": 182,
          "optimal_points": 274.73,
          "points_left": 92.73,
          "bench_points": 180.4,
          "efficiency_rate": 0.6625,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 0,
          "weeks": [
            {
              "week": 1,
              "actual": 107,
              "optimal": 145.73,
              "left": 38.73,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Britain Covey",
                  "points": 23.8
                },
                {
                  "player": "Mike Gesicki",
                  "points": 20.1
                },
                {
                  "player": "Dyami Brown",
                  "points": 16.4
                },
                {
                  "player": "Brady Russell",
                  "points": 9
                }
              ],
              "opponent_points": 77.3,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 75,
              "optimal": 129,
              "left": 54,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Mike Gesicki",
                  "points": 25.4
                },
                {
                  "player": "Dyami Brown",
                  "points": 21.7
                },
                {
                  "player": "Michael Pittman",
                  "points": 18
                },
                {
                  "player": "Brady Russell",
                  "points": 14.3
                },
                {
                  "player": "Lamar Jackson",
                  "points": 10.6
                }
              ],
              "opponent_points": 71,
              "lost_to_bench": false
            }
          ],
          "rank": 10
        },
        {
          "team_id": "12",
          "team": "Team 12",
          "manager": "owner12",
          "actual_points": 173.6,
          "optimal_points": 265.52,
          "points_left": 91.92,
          "bench_points": 180.4,
          "efficiency_rate": 0.6538,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 2,
          "weeks": [
            {
              "week": 1,
              "actual": 72.2,
              "optimal": 120.87,
              "left": 48.67,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Drake London",
                  "points": 23.8
                },
                {
                  "player": "T.J. Hockenson",
                  "points": 20.1
                },
                {
                  "player": "Simi Fehoko",
                  "points": 16.4
                },
                {
                  "player": "Bijan Robinson",
                  "points": 9
                }
              ],
              "opponent_points": 112.1,
              "lost_to_bench": true
            },
            {
              "week": 2,
              "actual": 101.4,
              "optimal": 144.65,
              "left": 43.25,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "T.J. Hockenson",
                  "points": 25.4
                },
                {
                  "player": "Simi Fehoko",
                  "points": 21.7
                },
                {
                  "player": "Darnell Mooney",
                  "points": 18
                },
                {
                  "player": "Josh Allen",
                  "points": 10.6
                }
              ],
              "opponent_points": 106.6,
              "lost_to_bench": true
            }
          ],
          "rank": 11
        },
        {
          "team_id": "5",
          "team": "Team 05",
          "manager": "owner05",
          "actual_points": 174.5,
          "optimal_points": 270.14,
          "points_left": 95.64,
          "bench_points": 180.4,
          "efficiency_rate": 0.646,
          "perfect_weeks": 0,
          "losses_the_bench_cost": 1,
          "weeks": [
            {
              "week": 1,
              "actual": 103.5,
              "optimal": 143.22,
              "left": 39.72,
              "bench": 87.3,
              "should_have_started": [
                {
                  "player": "Amon-Ra St. Brown",
                  "points": 23.8
                },
                {
                  "player": "Ian Thomas",
                  "points": 20.1
                },
                {
                  "player": "Tee Higgins",
                  "points": 16.4
                },
                {
                  "player": "Brian Robinson",
                  "points": 9
                }
              ],
              "opponent_points": 81.8,
              "lost_to_bench": false
            },
            {
              "week": 2,
              "actual": 71,
              "optimal": 126.92,
              "left": 55.92,
              "bench": 93.1,
              "should_have_started": [
                {
                  "player": "Ian Thomas",
                  "points": 25.4
                },
                {
                  "player": "Tee Higgins",
                  "points": 21.7
                },
                {
                  "player": "Terry McLaurin",
                  "points": 18
                },
                {
                  "player": "Brian Robinson",
                  "points": 14.3
                },
                {
                  "player": "Mitchell Trubisky",
                  "points": 10.6
                }
              ],
              "opponent_points": 75,
              "lost_to_bench": true
            }
          ],
          "rank": 12
        }
      ]
    },
    "yours": {
      "team_id": "7",
      "team": "Team 07",
      "manager": "owner07",
      "actual_points": 227.1,
      "optimal_points": 306.01,
      "points_left": 78.91,
      "bench_points": 180.4,
      "efficiency_rate": 0.7421,
      "perfect_weeks": 0,
      "losses_the_bench_cost": 1,
      "weeks": [
        {
          "week": 1,
          "actual": 129.7,
          "optimal": 164.08,
          "left": 34.38,
          "bench": 87.3,
          "should_have_started": [
            {
              "player": "Josh Palmer",
              "points": 23.8
            },
            {
              "player": "Tanner Hudson",
              "points": 20.1
            },
            {
              "player": "Breece Hall",
              "points": 9
            }
          ],
          "opponent_points": 116.6,
          "lost_to_bench": false
        },
        {
          "week": 2,
          "actual": 97.4,
          "optimal": 141.93,
          "left": 44.53,
          "bench": 93.1,
          "should_have_started": [
            {
              "player": "Tanner Hudson",
              "points": 25.4
            },
            {
              "player": "Rashod Bateman",
              "points": 21.7
            },
            {
              "player": "Deebo Samuel Sr.",
              "points": 18
            },
            {
              "player": "Joshua Dobbs",
              "points": 10.6
            }
          ],
          "opponent_points": 110.6,
          "lost_to_bench": true
        }
      ],
      "rank": 1
    }
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_7852248b8d749a604abe5a41"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

```http
GET https://api.askkelly.ai/v1/leagues/lg_dzs55c9tr5hqqr0ja1tt/analysis?analysis=luck
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_analysis",
  "league_analysis": {
    "analysis": "luck",
    "about": "schedule luck: the all-play record (every team every week), expected wins and wins gained or lost to the schedule",
    "league": {
      "id": "lg_dzs55c9tr5hqqr0ja1tt",
      "name": "Kelly Synthetic League (Sleeper shape)",
      "platform": "Sleeper",
      "platform_league_id": "1200000000000000001",
      "season": 2026,
      "week": 3,
      "your_team": "Team 07"
    },
    "your_team_id": "7",
    "available": true,
    "reason": null,
    "weeks": [
      1,
      2
    ],
    "result": {
      "median_game_left_out": false,
      "teams": [
        {
          "team_id": "10",
          "team": "Team 10",
          "manager": "owner10",
          "head_to_head_wins": 2,
          "games": 2,
          "expected_wins": 0.64,
          "luck_wins": 1.36,
          "record": "2-0",
          "all_play_record": "7-15",
          "all_play_win_rate": 0.3182,
          "points_for": 182,
          "points_against": 148.3,
          "opponents_above_their_average_per_game": -15.45,
          "wins_below_median": 1,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 107,
              "rank": 6,
              "teams": 12,
              "opponent_id": 3,
              "opponent": "Team 03",
              "opponent_points": 77.3,
              "result": "W",
              "teams_outscored": 6,
              "teams_tied": 0,
              "expected_win": 0.55,
              "luck": 0.45,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 75,
              "rank": 11,
              "teams": 12,
              "opponent_id": 5,
              "opponent": "Team 05",
              "opponent_points": 71,
              "result": "W",
              "teams_outscored": 1,
              "teams_tied": 0,
              "expected_win": 0.09,
              "luck": 0.91,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 1,
          "points_for_rank": 10,
          "points_against_rank": 12,
          "place": 3,
          "expected_place": 10
        },
        {
          "team_id": "2",
          "team": "Team 02",
          "manager": "owner02",
          "head_to_head_wins": 2,
          "games": 2,
          "expected_wins": 1.36,
          "luck_wins": 0.64,
          "record": "2-0",
          "all_play_record": "15-7",
          "all_play_win_rate": 0.6818,
          "points_for": 218.6,
          "points_against": 200.3,
          "opponents_above_their_average_per_game": 0,
          "wins_below_median": 1,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 125.2,
              "rank": 2,
              "teams": 12,
              "opponent_id": 11,
              "opponent": "Team 11",
              "opponent_points": 120.1,
              "result": "W",
              "teams_outscored": 10,
              "teams_tied": 0,
              "expected_win": 0.91,
              "luck": 0.09,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 93.4,
              "rank": 7,
              "teams": 12,
              "opponent_id": 1,
              "opponent": "Team 01",
              "opponent_points": 80.2,
              "result": "W",
              "teams_outscored": 5,
              "teams_tied": 0,
              "expected_win": 0.45,
              "luck": 0.55,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 2,
          "points_for_rank": 3,
          "points_against_rank": 7,
          "place": 2,
          "expected_place": 2
        },
        {
          "team_id": "9",
          "team": "Team 09",
          "manager": "owner09",
          "head_to_head_wins": 2,
          "games": 2,
          "expected_wins": 1.36,
          "luck_wins": 0.64,
          "record": "2-0",
          "all_play_record": "15-7",
          "all_play_win_rate": 0.6818,
          "points_for": 218.7,
          "points_against": 174.6,
          "opponents_above_their_average_per_game": -15.45,
          "wins_below_median": 1,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 94.9,
              "rank": 8,
              "teams": 12,
              "opponent_id": 4,
              "opponent": "Team 04",
              "opponent_points": 90.4,
              "result": "W",
              "teams_outscored": 4,
              "teams_tied": 0,
              "expected_win": 0.36,
              "luck": 0.64,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 123.8,
              "rank": 1,
              "teams": 12,
              "opponent_id": 6,
              "opponent": "Team 06",
              "opponent_points": 84.2,
              "result": "W",
              "teams_outscored": 11,
              "teams_tied": 0,
              "expected_win": 1,
              "luck": 0,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 3,
          "points_for_rank": 2,
          "points_against_rank": 9,
          "place": 1,
          "expected_place": 2
        },
        {
          "team_id": "5",
          "team": "Team 05",
          "manager": "owner05",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 0.45,
          "luck_wins": 0.55,
          "record": "1-1",
          "all_play_record": "5-17",
          "all_play_win_rate": 0.2273,
          "points_for": 174.5,
          "points_against": 156.8,
          "opponents_above_their_average_per_game": -15.2,
          "wins_below_median": 1,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 103.5,
              "rank": 7,
              "teams": 12,
              "opponent_id": 8,
              "opponent": "Team 08",
              "opponent_points": 81.8,
              "result": "W",
              "teams_outscored": 5,
              "teams_tied": 0,
              "expected_win": 0.45,
              "luck": 0.55,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 71,
              "rank": 12,
              "teams": 12,
              "opponent_id": 10,
              "opponent": "Team 10",
              "opponent_points": 75,
              "result": "L",
              "teams_outscored": 0,
              "teams_tied": 0,
              "expected_win": 0,
              "luck": 0,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 4,
          "points_for_rank": 11,
          "points_against_rank": 11,
          "place": 9,
          "expected_place": 12
        },
        {
          "team_id": "1",
          "team": "Team 01",
          "manager": "owner01",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 0.82,
          "luck_wins": 0.18,
          "record": "1-1",
          "all_play_record": "9-13",
          "all_play_win_rate": 0.4091,
          "points_for": 192.3,
          "points_against": 165.6,
          "opponents_above_their_average_per_game": -15.25,
          "wins_below_median": 0,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 112.1,
              "rank": 5,
              "teams": 12,
              "opponent_id": 12,
              "opponent": "Team 12",
              "opponent_points": 72.2,
              "result": "W",
              "teams_outscored": 7,
              "teams_tied": 0,
              "expected_win": 0.64,
              "luck": 0.36,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 80.2,
              "rank": 10,
              "teams": 12,
              "opponent_id": 2,
              "opponent": "Team 02",
              "opponent_points": 93.4,
              "result": "L",
              "teams_outscored": 2,
              "teams_tied": 0,
              "expected_win": 0.18,
              "luck": -0.18,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 5,
          "points_for_rank": 8,
          "points_against_rank": 10,
          "place": 7,
          "expected_place": 8
        },
        {
          "team_id": "3",
          "team": "Team 03",
          "manager": "owner03",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 0.82,
          "luck_wins": 0.18,
          "record": "1-1",
          "all_play_record": "9-13",
          "all_play_win_rate": 0.4091,
          "points_for": 183.9,
          "points_against": 208.4,
          "opponents_above_their_average_per_game": 15.3,
          "wins_below_median": 0,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 77.3,
              "rank": 11,
              "teams": 12,
              "opponent_id": 10,
              "opponent": "Team 10",
              "opponent_points": 107,
              "result": "L",
              "teams_outscored": 1,
              "teams_tied": 0,
              "expected_win": 0.09,
              "luck": -0.09,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 106.6,
              "rank": 4,
              "teams": 12,
              "opponent_id": 12,
              "opponent": "Team 12",
              "opponent_points": 101.4,
              "result": "W",
              "teams_outscored": 8,
              "teams_tied": 0,
              "expected_win": 0.73,
              "luck": 0.27,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 6,
          "points_for_rank": 9,
          "points_against_rank": 5,
          "place": 8,
          "expected_place": 8
        },
        {
          "team_id": "8",
          "team": "Team 08",
          "manager": "owner08",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 1,
          "luck_wins": 0,
          "record": "1-1",
          "all_play_record": "11-11",
          "all_play_win_rate": 0.5,
          "points_for": 192.4,
          "points_against": 200.9,
          "opponents_above_their_average_per_game": 0.05,
          "wins_below_median": 0,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 81.8,
              "rank": 10,
              "teams": 12,
              "opponent_id": 5,
              "opponent": "Team 05",
              "opponent_points": 103.5,
              "result": "L",
              "teams_outscored": 2,
              "teams_tied": 0,
              "expected_win": 0.18,
              "luck": -0.18,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 110.6,
              "rank": 3,
              "teams": 12,
              "opponent_id": 7,
              "opponent": "Team 07",
              "opponent_points": 97.4,
              "result": "W",
              "teams_outscored": 9,
              "teams_tied": 0,
              "expected_win": 0.82,
              "luck": 0.18,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 7,
          "points_for_rank": 7,
          "points_against_rank": 6,
          "place": 6,
          "expected_place": 6
        },
        {
          "team_id": "4",
          "team": "Team 04",
          "manager": "owner04",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 1.18,
          "luck_wins": -0.18,
          "record": "1-1",
          "all_play_record": "13-9",
          "all_play_win_rate": 0.5909,
          "points_for": 210.2,
          "points_against": 183.1,
          "opponents_above_their_average_per_game": -15.2,
          "wins_below_median": 0,
          "losses_above_median": 0,
          "weeks": [
            {
              "week": 1,
              "points": 90.4,
              "rank": 9,
              "teams": 12,
              "opponent_id": 9,
              "opponent": "Team 09",
              "opponent_points": 94.9,
              "result": "L",
              "teams_outscored": 3,
              "teams_tied": 0,
              "expected_win": 0.27,
              "luck": -0.27,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 119.8,
              "rank": 2,
              "teams": 12,
              "opponent_id": 11,
              "opponent": "Team 11",
              "opponent_points": 88.2,
              "result": "W",
              "teams_outscored": 10,
              "teams_tied": 0,
              "expected_win": 0.91,
              "luck": 0.09,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 8,
          "points_for_rank": 4,
          "points_against_rank": 8,
          "place": 5,
          "expected_place": 4
        },
        {
          "team_id": "7",
          "team": "Team 07",
          "manager": "owner07",
          "head_to_head_wins": 1,
          "games": 2,
          "expected_wins": 1.55,
          "luck_wins": -0.55,
          "record": "1-1",
          "all_play_record": "17-5",
          "all_play_win_rate": 0.7727,
          "points_for": 227.1,
          "points_against": 227.2,
          "opponents_above_their_average_per_game": 15.3,
          "wins_below_median": 0,
          "losses_above_median": 1,
          "weeks": [
            {
              "week": 1,
              "points": 129.7,
              "rank": 1,
              "teams": 12,
              "opponent_id": 6,
              "opponent": "Team 06",
              "opponent_points": 116.6,
              "result": "W",
              "teams_outscored": 11,
              "teams_tied": 0,
              "expected_win": 1,
              "luck": 0,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 97.4,
              "rank": 6,
              "teams": 12,
              "opponent_id": 8,
              "opponent": "Team 08",
              "opponent_points": 110.6,
              "result": "L",
              "teams_outscored": 6,
              "teams_tied": 0,
              "expected_win": 0.55,
              "luck": -0.55,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 9,
          "points_for_rank": 1,
          "points_against_rank": 3,
          "place": 4,
          "expected_place": 1
        },
        {
          "team_id": "12",
          "team": "Team 12",
          "manager": "owner12",
          "head_to_head_wins": 0,
          "games": 2,
          "expected_wins": 0.64,
          "luck_wins": -0.64,
          "record": "0-2",
          "all_play_record": "7-15",
          "all_play_win_rate": 0.3182,
          "points_for": 173.6,
          "points_against": 218.7,
          "opponents_above_their_average_per_game": 15.3,
          "wins_below_median": 0,
          "losses_above_median": 1,
          "weeks": [
            {
              "week": 1,
              "points": 72.2,
              "rank": 12,
              "teams": 12,
              "opponent_id": 1,
              "opponent": "Team 01",
              "opponent_points": 112.1,
              "result": "L",
              "teams_outscored": 0,
              "teams_tied": 0,
              "expected_win": 0,
              "luck": 0,
              "below_median": true,
              "above_median": false
            },
            {
              "week": 2,
              "points": 101.4,
              "rank": 5,
              "teams": 12,
              "opponent_id": 3,
              "opponent": "Team 03",
              "opponent_points": 106.6,
              "result": "L",
              "teams_outscored": 7,
              "teams_tied": 0,
              "expected_win": 0.64,
              "luck": -0.64,
              "below_median": false,
              "above_median": true
            }
          ],
          "luckiest_rank": 10,
          "points_for_rank": 12,
          "points_against_rank": 4,
          "place": 12,
          "expected_place": 10
        },
        {
          "team_id": "6",
          "team": "Team 06",
          "manager": "owner06",
          "head_to_head_wins": 0,
          "games": 2,
          "expected_wins": 1,
          "luck_wins": -1,
          "record": "0-2",
          "all_play_record": "11-11",
          "all_play_win_rate": 0.5,
          "points_for": 200.8,
          "points_against": 253.5,
          "opponents_above_their_average_per_game": 15.3,
          "wins_below_median": 0,
          "losses_above_median": 1,
          "weeks": [
            {
              "week": 1,
              "points": 116.6,
              "rank": 4,
              "teams": 12,
              "opponent_id": 7,
              "opponent": "Team 07",
              "opponent_points": 129.7,
              "result": "L",
              "teams_outscored": 8,
              "teams_tied": 0,
              "expected_win": 0.73,
              "luck": -0.73,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 84.2,
              "rank": 9,
              "teams": 12,
              "opponent_id": 9,
              "opponent": "Team 09",
              "opponent_points": 123.8,
              "result": "L",
              "teams_outscored": 3,
              "teams_tied": 0,
              "expected_win": 0.27,
              "luck": -0.27,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 11,
          "points_for_rank": 6,
          "points_against_rank": 1,
          "place": 11,
          "expected_place": 6
        },
        {
          "team_id": "11",
          "team": "Team 11",
          "manager": "owner11",
          "head_to_head_wins": 0,
          "games": 2,
          "expected_wins": 1.18,
          "luck_wins": -1.18,
          "record": "0-2",
          "all_play_record": "13-9",
          "all_play_win_rate": 0.5909,
          "points_for": 208.3,
          "points_against": 245,
          "opponents_above_their_average_per_game": 15.3,
          "wins_below_median": 0,
          "losses_above_median": 1,
          "weeks": [
            {
              "week": 1,
              "points": 120.1,
              "rank": 3,
              "teams": 12,
              "opponent_id": 2,
              "opponent": "Team 02",
              "opponent_points": 125.2,
              "result": "L",
              "teams_outscored": 9,
              "teams_tied": 0,
              "expected_win": 0.82,
              "luck": -0.82,
              "below_median": false,
              "above_median": true
            },
            {
              "week": 2,
              "points": 88.2,
              "rank": 8,
              "teams": 12,
              "opponent_id": 4,
              "opponent": "Team 04",
              "opponent_points": 119.8,
              "result": "L",
              "teams_outscored": 4,
              "teams_tied": 0,
              "expected_win": 0.36,
              "luck": -0.36,
              "below_median": true,
              "above_median": false
            }
          ],
          "luckiest_rank": 12,
          "points_for_rank": 5,
          "points_against_rank": 2,
          "place": 10,
          "expected_place": 4
        }
      ]
    },
    "yours": {
      "team_id": "7",
      "team": "Team 07",
      "manager": "owner07",
      "head_to_head_wins": 1,
      "games": 2,
      "expected_wins": 1.55,
      "luck_wins": -0.55,
      "record": "1-1",
      "all_play_record": "17-5",
      "all_play_win_rate": 0.7727,
      "points_for": 227.1,
      "points_against": 227.2,
      "opponents_above_their_average_per_game": 15.3,
      "wins_below_median": 0,
      "losses_above_median": 1,
      "weeks": [
        {
          "week": 1,
          "points": 129.7,
          "rank": 1,
          "teams": 12,
          "opponent_id": 6,
          "opponent": "Team 06",
          "opponent_points": 116.6,
          "result": "W",
          "teams_outscored": 11,
          "teams_tied": 0,
          "expected_win": 1,
          "luck": 0,
          "below_median": false,
          "above_median": true
        },
        {
          "week": 2,
          "points": 97.4,
          "rank": 6,
          "teams": 12,
          "opponent_id": 8,
          "opponent": "Team 08",
          "opponent_points": 110.6,
          "result": "L",
          "teams_outscored": 6,
          "teams_tied": 0,
          "expected_win": 0.55,
          "luck": -0.55,
          "below_median": false,
          "above_median": true
        }
      ],
      "luckiest_rank": 9,
      "points_for_rank": 1,
      "points_against_rank": 3,
      "place": 4,
      "expected_place": 1
    }
  },
  "as_of": "2026-10-04T17:30:00+00:00",
  "source": "kelly",
  "request_id": "req_f2c7eab1edb330a77d5d02e3"
}
```

Where each value comes from:

1. kelly · as of 2026-10-04T17:30:00+00:00

`GET /v1/me/league-actions`

## List your league moves
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_my_league_actions` · status live

Your league moves, newest first, with their status, channel and deep link; open=true for the ones still waiting on you or on the platform.

### Parameters
- `league_id` string · query  
  Only this league.  
  max length 40
- `open` boolean · query  
  Only moves still open.  
  default false
- `limit` integer · query  
  Moves to return, 1 to 100.  
  min 1 · max 100 · default 20

### Response
`200` Your moves, newest first.

- `object` const · required  
  Always list.  
  Always `"list"`.
- `data` array of object · required  
  The moves.
  - `object` const · required  
    Always league_action.  
    Always `"league_action"`.
  - `id` string · required  
    The move's ID (lga_…).  
    pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `league_id` string · required  
    Your connected league (lg_…).
  - `batch_id` string · nullable  
    The batch it was proposed in (lgb_…), when the same move went to several leagues.
  - `platform` string · required  
    The league's platform.  
    One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
  - `kind` string · required  
    The kind of move.  
    One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
  - `surface` string  
    Where it was proposed.  
    One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
  - `season` integer  
    The league's season.
  - `week` integer · nullable  
    The week the move is for.
  - `team_id` string  
    Your team in the league, as the platform numbers it.
  - `summary` string · required  
    The move in words, e.g. Start Breece Hall over Javonte Williams.
  - `status` string · required  
    proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
    One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
  - `status_words` string  
    The status in words.
  - `channel` string · nullable  
    How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
  - `channel_words` string · nullable  
    The channel in words.
  - `deep_link` string · nullable  
    The platform's page to finish the move on, for B1 and C.
  - `detail` string · nullable  
    What to do next, or why it failed.
  - `platform_ref` string · nullable  
    The platform's own ID for the move (a claim or trade), when it gave one.
  - `change` object · required  
    The exact change: ops in the platform's IDs, and the roster before and after.
  - `warnings` array of string  
    What to know before confirming, e.g. a drop can't be undone.
  - `confirm_token` string  
    Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
  - `confirm_expires_at` string · nullable  
    When the confirm_token expires.  
    format date-time
  - `deadline` string · nullable  
    When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
    format date-time
  - `single_step` boolean  
    Run without a separate confirm (a lineup from a key with write:lineups).
  - `reconfirms` integer  
    How many times the league changed before it was sent.
  - `undo` object  
    available, and in words how to undo it.
  - `undo_of` string · nullable  
    The move this one undoes.
  - `events` array of object  
    Every step, oldest first: status, time, channel and detail.
  - `confirmed_at` string · nullable  
    When you confirmed.  
    format date-time
  - `sent_at` string · nullable  
    When it was sent.  
    format date-time
  - `landed_at` string · nullable  
    When Kelly saw it in the league.  
    format date-time
  - `finished_at` string · nullable  
    When it finished.  
    format date-time
  - `created_at` string · nullable  
    When it was proposed.  
    format date-time
  - `updated_at` string · nullable  
    When it last changed.  
    format date-time
- `has_more` boolean · required  
  Always false: the list returns your newest moves, up to limit (at most 100).
- `next_cursor` string · required · nullable  
  Always null: there is no further page.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled)

### Example
```http
GET https://api.askkelly.ai/v1/me/league-actions
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

`POST /v1/me/league-actions`

## Propose a league move
scope `write:leagues` · 0 credits, not charged during the beta · status live

Plans a move in one of your connected leagues (kind and its params) against a fresh read of the league, and refuses one that can't work with the reason and the closest move that does. Send confirm: true with a key holding write:lineups to run a lineup in one step; drops, trades and keepers always confirm. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `league_id` string  
  Your connected league (lg_…).  
  min length 1 · max length 40
- `kind` string  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `params` object  
  The kind's parameters, as its own route takes them (PUT …/lineup and the rest).
- `confirm` boolean  
  true runs a lineup in one step; needs a key with write:lineups.

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
POST https://api.askkelly.ai/v1/me/league-actions
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "league_id": "lg_dzs55c9tr5hqqr0ja1tt",
  "kind": "drop",
  "params": {
    "player": "Josh Palmer"
  }
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_ee8fd6109d138443aff065f2",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/league-actions/batch`

## Propose a move in several leagues
scope `write:leagues` · 0 credits, not charged during the beta · status live

The same move in each league you list (bench a player everywhere), one action per league sharing a batch ID, each with its own confirm_token; a league where it can't work is listed under refused with the reason. Needs your own live key with write:leagues.

### Parameters
Body, `application/json` (required):

- `league_ids` array of string  
  Your connected leagues.  
  min items 1 · max items 20
- `kind` string  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `params` object  
  The kind's parameters, the same in every league.

### Response
`201` One proposal per league, and the leagues where it can't work.

- `object` const · required  
  Always league_action_batch.  
  Always `"league_action_batch"`.
- `batch_id` string · required  
  The batch (lgb_…).
- `actions` array of object · required  
  One proposal per league, each with its own confirm_token.
  - `object` const · required  
    Always league_action.  
    Always `"league_action"`.
  - `id` string · required  
    The move's ID (lga_…).  
    pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
  - `league_id` string · required  
    Your connected league (lg_…).
  - `batch_id` string · nullable  
    The batch it was proposed in (lgb_…), when the same move went to several leagues.
  - `platform` string · required  
    The league's platform.  
    One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
  - `kind` string · required  
    The kind of move.  
    One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
  - `surface` string  
    Where it was proposed.  
    One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
  - `season` integer  
    The league's season.
  - `week` integer · nullable  
    The week the move is for.
  - `team_id` string  
    Your team in the league, as the platform numbers it.
  - `summary` string · required  
    The move in words, e.g. Start Breece Hall over Javonte Williams.
  - `status` string · required  
    proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
    One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
  - `status_words` string  
    The status in words.
  - `channel` string · nullable  
    How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
  - `channel_words` string · nullable  
    The channel in words.
  - `deep_link` string · nullable  
    The platform's page to finish the move on, for B1 and C.
  - `detail` string · nullable  
    What to do next, or why it failed.
  - `platform_ref` string · nullable  
    The platform's own ID for the move (a claim or trade), when it gave one.
  - `change` object · required  
    The exact change: ops in the platform's IDs, and the roster before and after.
  - `warnings` array of string  
    What to know before confirming, e.g. a drop can't be undone.
  - `confirm_token` string  
    Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
  - `confirm_expires_at` string · nullable  
    When the confirm_token expires.  
    format date-time
  - `deadline` string · nullable  
    When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
    format date-time
  - `single_step` boolean  
    Run without a separate confirm (a lineup from a key with write:lineups).
  - `reconfirms` integer  
    How many times the league changed before it was sent.
  - `undo` object  
    available, and in words how to undo it.
  - `undo_of` string · nullable  
    The move this one undoes.
  - `events` array of object  
    Every step, oldest first: status, time, channel and detail.
  - `confirmed_at` string · nullable  
    When you confirmed.  
    format date-time
  - `sent_at` string · nullable  
    When it was sent.  
    format date-time
  - `landed_at` string · nullable  
    When Kelly saw it in the league.  
    format date-time
  - `finished_at` string · nullable  
    When it finished.  
    format date-time
  - `created_at` string · nullable  
    When it was proposed.  
    format date-time
  - `updated_at` string · nullable  
    When it last changed.  
    format date-time
- `refused` array of object · required  
  The leagues where it can't work, each with the reason.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large)

### Example
```http
POST https://api.askkelly.ai/v1/me/league-actions/batch
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "league_ids": [
    "lg_dzs55c9tr5hqqr0ja1tt"
  ],
  "kind": "watch",
  "params": {
    "player": "Josh Palmer",
    "on": true
  }
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_d3c1dca0c74ceb970e14caea",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`GET /v1/me/league-actions/{action_id}`

## Get a league move
scope `read:league` · 0 credits, not charged during the beta · status live

One of your league moves with its status and every step it took. Anyone else's answers 404.

### Parameters
- `action_id` string · path · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$ · max length 60

### Response
`200` The move as it now is.

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/me/league-actions/lga_00000000000000000000
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such league move on your account.",
  "param": "action_id",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_778b8a23cf3429e7bdad106e",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`POST /v1/me/league-actions/{action_id}/confirm`

## Confirm a league move
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `confirm_league_action` · status live

Runs a proposed move with its confirm_token. Just before sending Kelly reads the league again: a change that alters the move returns needs_reconfirm with a new confirm_token. Then the move goes by the platform's API, your browser, Kelly's browser or a link you finish, and Kelly checks it landed.

### Parameters
- `action_id` string · path · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$ · max length 60

Body, `application/json` (required):

- `confirm_token` string  
  The token, within 5 minutes of the proposal.  
  min length 8 · max length 200

### Response
`200` The move as it now is.

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found)

### Example
```http
POST https://api.askkelly.ai/v1/me/league-actions/lga_00000000000000000000/confirm
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "confirm_token": "lgc_00000000000000000000000000000000"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_c807de0620988126bade4e22",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/league-actions/{action_id}/cancel`

## Cancel a league move
scope `write:leagues` · 0 credits, not charged during the beta · status live

Cancels a move that hasn't been sent yet.

### Parameters
- `action_id` string · path · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$ · max length 60

### Response
`200` The move as it now is.

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
POST https://api.askkelly.ai/v1/me/league-actions/lga_00000000000000000000/cancel
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_ba0de15927eb0b3345149451",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/league-actions/{action_id}/undo`

## Undo a league move
scope `write:leagues` · 0 credits, not charged during the beta · status live

Proposes the reverse of a move that landed (swap back, cancel or drop a claim, withdraw an offer); it needs its own confirm. A drop or an accepted trade can't be undone.

### Parameters
- `action_id` string · path · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$ · max length 60

### Response
`201` The reverse move, proposed with its own confirm_token.

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
POST https://api.askkelly.ai/v1/me/league-actions/lga_00000000000000000000/undo
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_ca5f46cea0e10fd8c5070be4",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`GET /v1/me/leagues/needs`

## Get what needs fixing in your lineups
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_my_league_needs` · status live

Every starter in your connected leagues who is out, on bye, questionable or not matched, and every empty slot, before their games start: each with the fix Kelly makes (your highest-projected eligible bench player whose game hasn't started), the next choices, when the game starts and how the fix reaches the platform (send, fill or link). Starters whose games already started are under too_late; an Out player who can move to IR is under ir_watch. Read only.

### Parameters
- `league` string · query  
  Only this league (lg_…).  
  max length 40
- `too_late` boolean · query  
  false leaves out too_late.  
  default true

### Response
`200` What needs fixing, soonest game first.

- `object` const · required  
  Always league_needs.  
  Always `"league_needs"`.
- `as_of` string · required  
  When Kelly checked.  
  format date-time
- `rule` string  
  How Kelly picks a fix, in words.
- `counts` object · required  
  How many needs, too_late, ir_watch and leagues.
- `leagues` array of object · required  
  Each connected league: league_id, name, platform, sport, week, team_id, external_id (the platform's league ID), page_match (URL patterns of the platform's pages for it), mode (send, fill or link), synced_at, age_s, needs (how many), deep_link and error (why Kelly couldn't check it, or null).
- `needs` array of object · required  
  What needs the person before their games start, soonest first: id (stable across reads), league, kind (out, bye, empty_slot, at_risk, unmatched, late_flex), severity (fix, warn, info), slot, player, locks_at, locks_in_s, words, and fix (mode, how, gain, player_in, move, choices, deep_link) or null when no bench player fits.
- `too_late` array of object · required  
  Starters out or at risk whose game already started.
- `ir_watch` array of object · required  
  Out players who can move to an open IR slot (kind can_move_to_ir), with the move.
- `ir_rules` array of object  
  Each league's IR slots and how many are used.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/me/leagues/needs
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "object": "league_needs",
  "as_of": "2026-10-04T17:30:00Z",
  "rule": "Fix starts your highest-projected eligible bench player.",
  "counts": {
    "needs": 0,
    "too_late": 0,
    "ir_watch": 0,
    "leagues": 1
  },
  "leagues": [
    {
      "league_id": "lg_dzs55c9tr5hqqr0ja1tt",
      "name": "Kelly Synthetic League (Sleeper shape)",
      "platform": "sleeper",
      "sport": "nfl",
      "week": 3,
      "day": null,
      "team_id": "7",
      "external_id": "1200000000000000001",
      "page_match": [
        "sleeper.com/leagues/*1200000000000000001*"
      ],
      "mode": "fill",
      "synced_at": "2026-10-04T17:30:00+00:00",
      "age_s": 0,
      "needs": 0,
      "deep_link": "https://sleeper.com/leagues/1200000000000000001/team",
      "error": null
    }
  ],
  "needs": [],
  "too_late": [],
  "ir_watch": [],
  "ir_rules": [
    {
      "league_id": "lg_dzs55c9tr5hqqr0ja1tt",
      "platform": "sleeper",
      "slots": 1,
      "used": 1,
      "synced_at": "2026-10-04T17:30:00+00:00",
      "words": "1 IR slot, 1 used."
    }
  ],
  "request_id": "req_86af8dd77c709dc2d5a687cd"
}
```

`POST /v1/me/leagues/fixes`

## Fix your lineups
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `fix_my_lineups` · status live

Proposes one lineup move per league for the needs you tick (needs from GET /v1/me/leagues/needs, choose to pick another bench player), each with its confirm_token; then confirm them with batch_id and confirm. A key holding write:lineups may send confirm: true to do both in one call. Each league's result stands alone: done, checking, queued, waiting_on_you (finish it at deep_link) or failed. Needs your own live key with write:leagues.

### Parameters
Body, `application/json` (required):

- `needs` array of string  
  The needs to fix, by id.  
  min items 1 · max items 50
- `choose` object  
  Another bench player for a need, by need id: the player's platform ID, entity ID or name, from the need's choices.
- `league` string  
  Only this league's needs (lg_…).  
  max length 40
- `batch_id` string  
  The proposal's batch, to confirm it.  
  max length 60
- `confirm` one of several shapes  
  The proposal's moves with their confirm_token; or true, with needs, to propose and run them in one call (a key holding write:lineups).

### Response
`200` The confirmed fixes' results.

- `object` const · required  
  Always league_fixes.  
  Always `"league_fixes"`.
- `batch_id` string · required  
  The batch (lgb_…): send it back to confirm.
- `status` string · required  
  proposed (waiting for your confirm), done (every fix landed) or partial.  
  One of: `proposed`, `done`, `partial` (open: new values may be added).
- `rule` string  
  How Kelly picks a fix, in words.
- `groups` array of object  
  A proposal's fixes by how they reach the platform (mode send, fill or link, how, count), each fix with its need_id, league, words, gain, locks_at and the league action with its confirm_token.
- `refused` array of object  
  Needs Kelly can't fix, each with the reason.
- `confirm_by` string · nullable  
  When the first confirm_token expires.  
  format date-time
- `counts` object  
  After confirming: how many fixes are done, checking, queued, waiting_on_you and failed.
- `results` array of object  
  After confirming: each fix's need_id, league_id, mode, result (done, checking, queued, waiting_on_you, failed), words, next, undo, deep_link and the league action.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found)

### Example
```http
POST https://api.askkelly.ai/v1/me/leagues/fixes
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "needs": [
    "need_00000000000000000000"
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_94c2a045d9eac6dd7fc5a390",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`GET /v1/me/leagues/week`

## Get your week plan
scope `read:league` · 0 credits, not charged during the beta · MCP tool `get_my_league_week` · status live

For your basketball, hockey or baseball league: who starts each day for the rest of the scoring period, the games left on the bench, today's lineup and whether it differs from the platform's, the opponent's plan, each category's odds and the week's in a category league, and the best add/drop moves from the free agents. Worked out from the league as Kelly last read it. Read only.

### Parameters
- `league` string · query  
  The league (lg_…); left out, your newest basketball, hockey or baseball league.  
  max length 40
- `moves` boolean · query  
  false leaves out the add/drop moves.  
  default true

### Response
`200` The week plan.

- `object` const · required  
  Always league_week.  
  Always `"league_week"`.
- `as_of` string · required  
  When Kelly worked it out.  
  format date-time
- `engine_version` string  
  The daily engine's version.
- `league` object · required  
  The league: id (lg_…), name, platform, sport (nba, nhl or mlb), season, team_id and team (yours) and read_at (the day of the rosters Kelly last read).
- `period` object · nullable  
  The scoring period: period, starts_on, ends_on and playoff; null outside the season.
- `today` string · required  
  The league's day the plan starts from.  
  format date
- `opponent` object · nullable  
  This period's opponent: team_id and team; null with none.
- `format` string  
  The league's scoring: h2h_each, h2h_most, h2h_points, points or roto.
- `measure` string · required  
  What the plan maximises: categories, points or roto.  
  One of: `categories`, `points`, `roto` (open: new values may be added).
- `plan` object · required  
  Your plan for the rest of the period: starts, possible_starts, games_left_on_bench, days (each day's starters with pid, name, slot and locked), wasted (a game left on the bench) and empty (a slot with nobody to start).
- `lineup_today` object · nullable  
  Today's lineup as the plan sets it (day, lineup with every player's slot and BN for the bench, changed: whether it differs from the lineup on the platform).
- `opponent_plan` object · nullable  
  The opponent's starts, possible_starts and games_left_on_bench.
- `matchup` object · nullable  
  A category league's matchup: categories (each with mine_now, opp_now, mine, opp, margin, p_win, p_tie, p_loss, decided and tracked), expected_won of of, p_win_week, p_tie_week, closest, minimums and draws; null in a points or roto league.
- `moves` array of object · required  
  The best add/drop swaps from the free agents, best first: add, drop, via (add or claim), arrives, gain, measure, starts_added and categories (each category's change in win chance).
- `adds_left` integer · nullable  
  Adds left this period; null with no limit.
- `unresolved` array of string  
  Categories Kelly can't track in this league yet.
- `estimated` array of string  
  Ratio categories whose totals so far Kelly estimated.
- `unmatched` array of string  
  Your players Kelly couldn't match to its own.

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`not_found`](/problems/not_found)

### Example
```http
GET https://api.askkelly.ai/v1/me/leagues/week
Authorization: Bearer $KELLY_API_KEY
```

```json
{
  "type": "https://docs.askkelly.ai/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No basketball, hockey or baseball league is connected yet: connect one in Settings, Leagues.",
  "param": "league",
  "doc_url": "https://docs.askkelly.ai/problems/not_found",
  "request_id": "req_d4422deb1fe0fcdcad4982ff",
  "retryable": false,
  "display_message": "That could not be found."
}
```

`PUT /v1/me/leagues/{league_id}/lineup`

## Set your lineup
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `set_my_lineup` · status live

Swaps, starts, benches, IR and taxi moves, or exact slots, in this week's lineup. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `swaps` array of object  
  Swaps, e.g. [{"in": "Breece Hall", "out": "Javonte Williams"}].  
  max items 20
  - `in` string · required  
    The player going into the lineup.  
    min length 1 · max length 80
  - `out` string · required  
    The player coming out; he takes the other's slot.  
    min length 1 · max length 80
- `start` array of string  
  Bench players to start in an open slot they can play.  
  max items 30
- `bench` array of string  
  Starters to move to the bench (their slots are left empty).  
  max items 30
- `ir` array of string  
  Players to move to IR.  
  max items 30
- `taxi` array of string  
  Players to move to the taxi squad.  
  max items 30
- `set` object  
  Exact slots by player, e.g. {"Breece Hall": "FLEX"}.
- `confirm` boolean  
  true runs the lineup in one step; needs a key with write:lineups.

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
PUT https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/lineup
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "swaps": [
    {
      "in": "Cole Kmet",
      "out": "Hunter Henry"
    }
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_308b7c725ca425fb9cfa3304",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/leagues/{league_id}/claims`

## Claim a player
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `claim_player` · status live

Adds a free agent or puts in a waiver claim, with a FAAB bid checked against what you have left and the drop a full roster needs. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `add` string  
  The free agent to add.  
  min length 1 · max length 80
- `drop` string  
  The player to drop for him.  
  min length 1 · max length 80
- `bid` integer  
  The FAAB bid in dollars.  
  min 0 · max 10000
- `group` string  
  A claim group: claims sharing it are tried in order until one wins (if A fails, take B).  
  max length 40

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
POST https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/claims
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "add": "Josh Palmer",
  "drop": "Cole Kmet",
  "bid": 7
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_4e77c71534e0c040f6ccb07f",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`PATCH /v1/me/leagues/{league_id}/claims`

## Change your claims
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `update_my_claims` · status live

Cancels pending waiver claims or sets their order. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `cancel` array of string  
  The claims to cancel, by the platform's claim ID.  
  max items 30
- `order` array of string  
  Every pending claim in the new order, first first.  
  max items 30

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
PATCH https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/claims
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "order": [
    "Josh Palmer"
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_2293b2611b5822527a083c54",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/leagues/{league_id}/drops`

## Drop a player
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `drop_player` · status live

Drops a player to waivers; a drop can't be undone, so it always confirms. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `player` string  
  The player to drop.  
  min length 1 · max length 80

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
POST https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/drops
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "player": "Josh Palmer"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_97cb4e336e3e66e8bb5e411b",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/leagues/{league_id}/trades`

## Offer a trade
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `propose_trade` · status live

Offers a trade to another team, with a note. At most 5 new offers per league a day and 2 to the same manager. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `to_team` string  
  The other team: its name, its manager or the platform's team number.  
  min length 1 · max length 80
- `give` array of string  
  The players you give.  
  max items 30
- `get` array of string  
  The players you ask for, all on that team.  
  max items 30
- `picks_give` array of string  
  Draft picks you give, e.g. 2027 round 2.  
  max items 10
- `picks_get` array of string  
  Draft picks you ask for.  
  max items 10
- `note` string  
  A note to the other manager.  
  max length 280

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
POST https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/trades
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "to_team": "Team 03",
  "give": [
    "Cole Kmet"
  ],
  "get": [
    "Hunter Henry"
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_4067aa093d59adcedec0abb5",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`POST /v1/me/leagues/{league_id}/trades/{trade_id}/respond`

## Answer a trade offer
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `respond_to_trade` · status live

Accepts, declines, counters or withdraws an offer; accepting can't be undone. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60
- `trade_id` string · path · required  
  The offer's ID on the platform.  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `answer` string  
  accept, reject, counter or withdraw. Accepting can't be undone.  
  One of: `accept`, `reject`, `counter`, `withdraw` (open: new values may be added).
- `counter` object  
  With counter: the trade you offer instead (give, get, picks).
- `from_team_name` string  
  The team that sent it, for the summary.  
  max length 80

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
POST https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/trades/1234/respond
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "answer": "reject"
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_c1768422e3b3099539e8be26",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`PUT /v1/me/leagues/{league_id}/keepers`

## Name your keepers
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `set_my_keepers` · status live

Names this season's keepers. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `players` array of string  
  The players to keep.  
  max items 30

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
PUT https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/keepers
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "players": [
    "Josh Palmer"
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_575ce02812ce076429d73aad",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`PUT /v1/me/leagues/{league_id}/watch`

## Watch a player
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `update_my_watch_list` · status live

Adds a player to your watch list or takes him off. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `player` string  
  The player.  
  min length 1 · max length 80
- `on` boolean  
  true (default) adds him; false takes him off.

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
PUT https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/watch
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "player": "Josh Palmer",
  "on": true
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_e45629d25ad8cdfd973f4f43",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

`PUT /v1/me/leagues/{league_id}/draft/queue`

## Set your draft queue
scope `write:leagues` · 0 credits, not charged during the beta · MCP tool `set_draft_queue` · status live

Sets your draft queue, first pick first. The result is the league action with the status contract: status (proposed, queued, sent, awaiting_person, landed, failed, expired, cancelled or needs_reconfirm), channel, and deep_link when you finish it on the platform. A proposal carries confirm_token; send it to POST /v1/me/league-actions/{action_id}/confirm within 5 minutes. Needs your own live key with write:leagues.

### Parameters
- `league_id` string · path · required  
  Your connected league (lg_…).  
  max length 60

- `Idempotency-Key` string · header  
  Makes a non-idempotent request safe to retry; kept at least 24 hours (API-IDEM-1).  
  min length 1 · max length 255

Body, `application/json` (required):

- `players` array of string  
  The players, first first.  
  max items 30

### Response
`201` The move, proposed with its confirm_token (or run, in one step).

- `object` const · required  
  Always league_action.  
  Always `"league_action"`.
- `id` string · required  
  The move's ID (lga_…).  
  pattern ^lga_[0123456789abcdefghjkmnpqrstvwxyz]{20}$
- `league_id` string · required  
  Your connected league (lg_…).
- `batch_id` string · nullable  
  The batch it was proposed in (lgb_…), when the same move went to several leagues.
- `platform` string · required  
  The league's platform.  
  One of: `sleeper`, `espn`, `yahoo`, `mfl`, `fantrax`, `cbs`, `fleaflicker` (open: new values may be added).
- `kind` string · required  
  The kind of move.  
  One of: `lineup`, `claim`, `update_claims`, `drop`, `propose_trade`, `respond_trade`, `keepers`, `watch`, `draft_queue` (open: new values may be added).
- `surface` string  
  Where it was proposed.  
  One of: `panel`, `chat`, `api`, `mcp`, `extension`, `autopilot` (open: new values may be added).
- `season` integer  
  The league's season.
- `week` integer · nullable  
  The week the move is for.
- `team_id` string  
  Your team in the league, as the platform numbers it.
- `summary` string · required  
  The move in words, e.g. Start Breece Hall over Javonte Williams.
- `status` string · required  
  proposed (waiting for your confirm), queued (waiting for a way to send it), sent, awaiting_person (finish it on the platform at deep_link), landed (Kelly saw it in the league), failed, expired, cancelled or needs_reconfirm (the league changed: confirm the new plan with the new confirm_token).  
  One of: `proposed`, `queued`, `sent`, `awaiting_person`, `landed`, `failed`, `expired`, `cancelled`, `needs_reconfirm` (open: new values may be added).
- `status_words` string  
  The status in words.
- `channel` string · nullable  
  How it goes: A the platform's API, B2 your browser sends, B1 your browser fills the screen and you press Save, D Kelly's browser, C a link you finish.
- `channel_words` string · nullable  
  The channel in words.
- `deep_link` string · nullable  
  The platform's page to finish the move on, for B1 and C.
- `detail` string · nullable  
  What to do next, or why it failed.
- `platform_ref` string · nullable  
  The platform's own ID for the move (a claim or trade), when it gave one.
- `change` object · required  
  The exact change: ops in the platform's IDs, and the roster before and after.
- `warnings` array of string  
  What to know before confirming, e.g. a drop can't be undone.
- `confirm_token` string  
  Returned once, on a proposal and on needs_reconfirm: send it to confirm within 5 minutes. Kelly keeps only its hash.
- `confirm_expires_at` string · nullable  
  When the confirm_token expires.  
  format date-time
- `deadline` string · nullable  
  When the move stops making sense (a player's game starts or waivers run); a move not landed by then expires.  
  format date-time
- `single_step` boolean  
  Run without a separate confirm (a lineup from a key with write:lineups).
- `reconfirms` integer  
  How many times the league changed before it was sent.
- `undo` object  
  available, and in words how to undo it.
- `undo_of` string · nullable  
  The move this one undoes.
- `events` array of object  
  Every step, oldest first: status, time, channel and detail.
- `confirmed_at` string · nullable  
  When you confirmed.  
  format date-time
- `sent_at` string · nullable  
  When it was sent.  
  format date-time
- `landed_at` string · nullable  
  When Kelly saw it in the league.  
  format date-time
- `finished_at` string · nullable  
  When it finished.  
  format date-time
- `created_at` string · nullable  
  When it was proposed.  
  format date-time
- `updated_at` string · nullable  
  When it last changed.  
  format date-time

### Errors
[`invalid_request`](/problems/invalid_request) · [`credential_in_url`](/problems/credential_in_url) · [`unsupported_api_version`](/problems/unsupported_api_version) · [`unauthenticated`](/problems/unauthenticated) · [`method_not_allowed`](/problems/method_not_allowed) · [`rate_limited`](/problems/rate_limited) · [`internal_error`](/problems/internal_error) · [`service_unavailable`](/problems/service_unavailable) · [`insufficient_scope`](/problems/insufficient_scope) · [`not_entitled`](/problems/not_entitled) · [`payload_too_large`](/problems/payload_too_large) · [`not_found`](/problems/not_found) · [`idempotency_key_reused`](/problems/idempotency_key_reused)

### Example
```http
PUT https://api.askkelly.ai/v1/me/leagues/lg_dzs55c9tr5hqqr0ja1tt/draft/queue
Authorization: Bearer $KELLY_API_KEY
Content-Type: application/json

{
  "players": [
    "Josh Palmer"
  ]
}
```

```json
{
  "type": "https://docs.askkelly.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This needs the write:leagues scope.",
  "param": "write:leagues",
  "doc_url": "https://docs.askkelly.ai/problems/insufficient_scope",
  "request_id": "req_9d4fb9433fdbc5312ed3f92e",
  "retryable": false,
  "display_message": "This app needs one more permission to do that."
}
```

Generated from Kelly API 2026-10-05.

---

Generated from Kelly API 2026-10-05

Support: support@askkelly.ai · Security and disclosure: https://docs.askkelly.ai/security

Data is the edge. Odds are information, not advice · 21+ · Get help
