Sports

Scores, schedules, standings, stats and game timelines from the sports pages on x.com. NFL, college football (NCAAFB) and MLB each have their own methods, and the league-wide methods take a league key such as "NFL" or "MLB".

Most methods return the useful part of the GraphQL response as Twitter sends it, in snake case. IDs are rest IDs as strings. You get game IDs from a schedule, team IDs from a teams list, and team account user IDs from team_information.preferred_twitter_user_results.rest_id on any team.

const games = await client.sports.nflSchedule();
const game = await client.sports.nflGame(games[0].rest_id);
const tweets = await client.sports.gameTimeline(games[0].rest_id);

`sports.gameTimeline(gameId, opts?)`

Get the tweets attached to a game from any league. Returns a parsed timeline. Uses SportsGameTopTimeline, or SportsGameLatestTimeline when opts.product is "latest".

Option	Type	Description
`gameId`	`string`	A game rest ID
`opts.product`	`string`	`"top"` (default) or `"latest"`
`opts.count`	`number`	Number of results (default 20)
`opts.cursor`	`string`	Pagination cursor
`opts.variables`	`object`	Additional GraphQL variables

const top = await client.sports.gameTimeline("2054558374415540224");
const latest = await client.sports.gameTimeline("2054558374415540224", { product: "latest" });

`sports.hub(league)`

Get the sports hub entry for a league, with its name, logo and timeline ID. Uses SportsHubBySport.

const nfl = await client.sports.hub("nfl");

`sports.hubTrends(rawQuery, opts?)`

Get current AI trends that match a query. Uses SportsHubTrends.

Option	Type	Description
`opts.limit`	`number`	Number of trends (default 20)
`opts.maxAgeHours`	`number`	Oldest trend age (default 24)
`opts.scoreThreshold`	`number`	Lowest relevance (default 0)

const trends = await client.sports.hubTrends("MLB", { limit: 5 });

`sports.leagueTeams(league)`

List the teams of a league with their semantic core IDs, which the follow methods take. Uses SportsProductLeagueTeams.

const teams = await client.sports.leagueTeams("MLB");

`sports.followedTeams(league)`

List the teams you follow in a league. Uses SportsProductFollowedTeamsV2.

const mine = await client.sports.followedTeams("NFL");

`sports.favoriteTeams()`

List your favorite teams across leagues. Uses SportsProductFollowedTeams.

const favorites = await client.sports.favoriteTeams();

`sports.followedTeamIds()`

List the IDs of the teams you follow. Uses FollowedTeams.

const ids = await client.sports.followedTeamIds();

`sports.leagueMedia(league)`

Get live broadcasts, recent broadcasts and media series for a league. Returns { liveBroadcasts, recentBroadcasts, series }. Uses SportsProductLeagueMediaSeries.

const { recentBroadcasts } = await client.sports.leagueMedia("NFL");

`sports.isFollowingLeague(league)`

Check whether you follow a league. Returns a boolean. Uses SportsLeagueFollow.

const following = await client.sports.isFollowingLeague("MLB");

`sports.userProfile(userId, opts?)`

Get the sports profile of a team account, with its league, schedule and roster. Uses UserSportsProfile. opts.startTime and opts.endTime set the schedule window in epoch milliseconds, and default to 8 days back and 14 days ahead.

const profile = await client.sports.userProfile("59471027");

`sports.profileSchedule(userId, opts?)`

Get the season schedule shown on a team account's profile. Takes the same window options as userProfile. Uses ProfileSeasonSchedule.

const schedule = await client.sports.profileSchedule("59471027");

`sports.profileRoster(userId)`

Get the player roster shown on a team account's profile. Uses ProfileTeamRoster.

const roster = await client.sports.profileRoster("59471027");

`sports.rosterFollowState(teamId)`

Check how many players of a team you can follow and whether you follow them all. Returns { followableCount, followed }. Uses SportsTeamRosterFollowState.

const state = await client.sports.rosterFollowState("689566309051330560");

`sports.gameReminders(opts?)`

List your game reminders. Uses SportsProductGameReminders.

const reminders = await client.sports.gameReminders();

`sports.liveViewers(gameId, opts?)`

Get how many people are watching a game right now. opts.league defaults to "NFL". Uses SportsProductLiveViewers.

const { viewers } = await client.sports.liveViewers("2054558374423875584");

`sports.chatState(gameId, opts?)`

Get whether the live chat of a game is open and how long until it opens. Uses SportsProductChatState.

const chat = await client.sports.chatState("2054558374423875584");

`sports.teamPicker(gameId, opts?)`

Get the "who will win" picker for a game and your current pick. Uses SportsProductTeamPicker.

const picker = await client.sports.teamPicker("2054558374423875584");

`sports.teamTallies(gameId, opts?)`

Get how many people picked each team in a game. Uses SportsProductTeamTallies.

const tallies = await client.sports.teamTallies("2054558374423875584");

`sports.notificationSettings()`

List your team notification settings. Uses SportsProductTeamNotificationSettings.

const settings = await client.sports.notificationSettings();

`sports.nflCurrentWeek()`

Get the current NFL week number. Uses CurrentNflWeek.

const week = await client.sports.nflCurrentWeek();

`sports.nflSchedule(opts?)`

List NFL games in a time window. Uses NFLSchedule.

Option	Type	Description
`opts.startTime`	`number`	Window start in ms (default 8 days back)
`opts.endTime`	`number`	Window end in ms (default 14 days ahead)
`opts.teamId`	`string`	Only games for this team

const games = await client.sports.nflSchedule();

`sports.nflWeeklySchedule(week, opts?)`

Get the NFL games and byes of one week. Returns { byes, games }. Set opts.previousYear to read last season. Uses NFLWeeklySchedule.

const { games, byes } = await client.sports.nflWeeklySchedule(5);

`sports.nflWeeklyStats(week, opts?)`

Get NFL stat leaders for one week. Uses NFLWeeklyStats.

const stats = await client.sports.nflWeeklyStats(4);

`sports.nflInjuries()`

Get the weekly NFL injury report. Uses NFLWeeklyInjuries. During testing Twitter sent an empty response and this returned null.

const injuries = await client.sports.nflInjuries();

`sports.nflStandings()`

Get the NFL standings, one row per team. Uses NFLStandings.

const standings = await client.sports.nflStandings();

`sports.nflSeasonStats()`

Get NFL stat leaders for the season. Uses NFLSeasonStats.

const stats = await client.sports.nflSeasonStats();

`sports.nflTeams()`

List all 32 NFL teams. Uses NFLTeams.

const teams = await client.sports.nflTeams();

`sports.nflFollowableTeams()`

List the NFL teams you can follow as a sports product. Uses SportsProductNflTeams.

const teams = await client.sports.nflFollowableTeams();

`sports.nflGame(gameId, opts?)`

Get an NFL game with teams, venue, scores and each team's recent games. Set opts.includeRecentGames to false for a smaller response. Uses NFLGameHydrate.

const game = await client.sports.nflGame("2054558374415540224");

`sports.nflLiveGame(gameId)`

Get the live state of an NFL game with play by play. Uses NFLLiveGame.

const live = await client.sports.nflLiveGame("2054558374415540224");

`sports.nflGameOdds(gameId)`

Get betting odds for an NFL game. Uses NFLGameOdds. During testing Twitter returned no odds for the burner account and this returned null.

const odds = await client.sports.nflGameOdds("2054558374423875584");

`sports.nflGamePlayerProps(gameId)`

Get player prop bets for an NFL game. Uses NFLGamePlayerProps. Like nflGameOdds, this returned null during testing.

const props = await client.sports.nflGamePlayerProps("2054558374423875584");

`sports.nflGameRoster(gameId)`

Get both team rosters for an NFL game. Uses NFLGameRoster.

const rosters = await client.sports.nflGameRoster("2054558374415540224");

`sports.nflMatchup(awayTeamId, homeTeamId, seasonId)`

Compare two NFL teams over a season with their stat leaders. The season ID is basic_data.season on a game from nflGame. Uses NFLMatchupSeason.

const game = await client.sports.nflGame("2054558374415540224");
const matchup = await client.sports.nflMatchup("689566309051330560", "689566314990436352", game.basic_data.season);

`sports.nflTeamHighlights(teamId)`

Get highlights from an NFL team's last game. Uses NFLTeamLastGameHighlights.

const highlights = await client.sports.nflTeamHighlights("689566304366292992");

`sports.nflTop100(opts?)`

Get the NFL Top 100 players list. opts.year picks a past list. Uses NflTop100.

const top = await client.sports.nflTop100({ year: 2025 });

`sports.isFollowingNfl()`

Check whether you follow the NFL. Returns a boolean. Uses NflScoresSidebarFollow.

const following = await client.sports.isFollowingNfl();

`sports.ncaafbSchedule(opts?)`

List college football games in a time window. Takes opts.startTime and opts.endTime like nflSchedule. Uses NCAAFBSchedule.

const games = await client.sports.ncaafbSchedule();

`sports.ncaafbGame(gameId)`

Get a college football game with teams, scores and recent games. Uses NCAAFBGameHydrate.

const game = await client.sports.ncaafbGame("2083346086815555585");

`sports.ncaafbLiveGame(gameId)`

Get the live state of a college football game with play by play. Uses NCAAFBLiveGame.

const live = await client.sports.ncaafbLiveGame("2083346086815555585");

`sports.ncaafbGameOdds(gameId)`

Get betting odds for a college football game. Uses NCAAFBGameOdds. This returned null during testing.

const odds = await client.sports.ncaafbGameOdds("2083346086815555585");

`sports.ncaafbStandings()`

Get the college football standings. Uses NCAAFBStandings.

const standings = await client.sports.ncaafbStandings();

`sports.ncaafbSeasonStats()`

Get college football stat leaders for the season. Uses NCAAFBSeasonStats.

const stats = await client.sports.ncaafbSeasonStats();

`sports.mlbSchedule(opts?)`

List MLB games in a time window. Uses MLBSchedule.

Option	Type	Description
`opts.startMs`	`number`	Window start in ms (default one day back)
`opts.endMs`	`number`	Window end in ms (default 7 days ahead)
`opts.includeOdds`	`boolean`	Include betting odds on each game
`opts.limit`	`number`	Most games to return (default 500)

const games = await client.sports.mlbSchedule({ includeOdds: true });

`sports.mlbScheduleDays(opts?)`

List MLB game IDs, times and statuses in a time window, which is enough to draw a calendar. The window defaults to 30 days on each side of now. Uses MLBScheduleDays.

const days = await client.sports.mlbScheduleDays();

`sports.mlbGame(gameId, opts?)`

Get an MLB game with box score, lineups and plays. Set opts.includeLineupSeasonStats to add season stats to the lineups. Uses MLBGameHydrate.

const game = await client.sports.mlbGame("93797801933991936");

`sports.mlbLiveGame(gameId)`

Get the live state of an MLB game. Uses MLBLiveGame.

const live = await client.sports.mlbLiveGame("93797801933991936");

`sports.mlbGameOdds(gameId)`

Get betting odds for an MLB game. Uses MLBGameOdds.

const odds = await client.sports.mlbGameOdds("93797801928564736");

`sports.mlbGamePlayerProps(gameId)`

Get player prop bets for an MLB game. Uses MLBGamePlayerProps.

const props = await client.sports.mlbGamePlayerProps("93797801928564736");

`sports.mlbMatchup(awayTeamId, homeTeamId, opts?)`

Compare two MLB teams with injuries, leaders and recent games. opts.recentStartMs and opts.recentEndMs set the recent games window, which defaults to the last year. Uses MLBMatchup.

const matchup = await client.sports.mlbMatchup("769193695664934912", "769193694494793728");

`sports.mlbPlayer(playerId)`

Get an MLB player's profile and stats. Player IDs come from box scores and leader lists. Uses MLBPlayerProfile.

const kwan = await client.sports.mlbPlayer("1502776566647951363");

`sports.mlbLeaders(opts?)`

Get MLB stat leaders by category. opts.league defaults to "all" and opts.limit to 25. Uses MLBLeaders.

const categories = await client.sports.mlbLeaders();

`sports.mlbPostseason(seasonYear)`

List the MLB postseason rounds and their series for a year. Uses MLBPostseasonRounds.

const rounds = await client.sports.mlbPostseason(2026);

`sports.mlbStandings()`

Get the MLB standings by league and division. Uses MLBStandings.

const standings = await client.sports.mlbStandings();

`sports.mlbTeams()`

List all 30 MLB teams. Uses MLBTeams.

const teams = await client.sports.mlbTeams();