SportFeeds API Documentation

Real-time, verified sports posts from X — filtered by league, team, player, game, or geo. Bring your own X API key, pay only for the data you query.

Quick Start

Get your first API response in under a minute

curl -H "Authorization: YOUR_API_KEY" "https://api.sportfeeds.com/v1/posts?league=NFL"

Real-time Feeds

Posts indexed within seconds of going live.

Verified Data

Tagged with players, teams, leagues, and games.

Low Latency

Sub-second p95 from cached endpoints.

Authorization

All SportFeeds API endpoints require authentication via the Authorization header.

Authentication Method

API Key via Authorization header

curl -H "Authorization: YOUR_API_KEY" "https://api.sportfeeds.com/v1/posts?league=NFL"

Manage your keys from the Dashboard.

For AI Agents

Drop the full schema into your agent's context with a single file.

openapi.json llms-full.txt llms.txt

GET

/posts

Unified

One endpoint, six modes. Filter by league, team, player, game, geo, or omit everything to get trending. Mode is auto-selected by which params you pass.

Overview

Endpoint

GET https://api.sportfeeds.com/v1/posts

Query Modes

Trending

GET /v1/posts

By League

GET /v1/posts?league=NFL,NBA

By Team(s)

GET /v1/posts?id_type=espn_guid&teams=...,...

By Player(s)

GET /v1/posts?id_type=espn_guid&players=...,...

By Game

GET /v1/posts?id_type=espn_guid&match=teamA,teamB&start_time=2024-01-15T20:00:00Z

Nearby (Geo)

GET /v1/posts?lat=40.71&lng=-74.00&radius_km=50

Parameters

Parameter	Required	Type	Example	Description
`league`	Optional	String (CSV)	`NFL,NBA`	Comma-separated leagues, or `ALL`.
`teams`	Optional	String (CSV)	`s:40~l:46~t:13`	Team IDs (≤10). Pair with `id_type`.
`players`	Optional	String (CSV)	`1f6592b3-...`	Player IDs (≤100). Pair with `id_type`.
`id_type`	Optional	String	`espn_guid`	ID system used by `teams`/`players` (espn_guid, espn_uid, sportradar, code, ...)
`match`	Optional	String	`teamA,teamB`	Two team IDs comma-separated; combined with `start_time` to query a specific game.
`start_time`	Optional	ISO timestamp	`2024-01-15T20:00:00Z`	Game start time (paired with `match`).
`include_pregame`	Optional	Boolean	`true`	Include pregame posts when querying a game.
`lat`	Optional	Float	`40.7128`	Latitude (with `lng` and optionally `radius_km`).
`lng`	Optional	Float	`-74.0060`	Longitude.
`radius_km`	Optional	Integer	`50`	Search radius in km (default 145, max 4830).
`media_type`	Optional	String	`video`	Filter by media type: photo, video, gif, animated_gif, none
`aspect_ratio`	Optional	String	`landscape`	Filter by aspect ratio: landscape, portrait, square
`min_score`	Optional	Integer	`5`	Minimum engagement score (0–9). 7+ = top performing, 8–9 = viral.
`min_duration`	Optional	Integer (ms)	`10000`	Minimum video duration in milliseconds.
`highlight`	Optional	Boolean	`true`	Return only highlight clips.
`has_player`	Optional	Boolean	`true`	Return only posts with at least one tagged player.
`custom_sources`	Optional	Boolean	`true`	Include posts from your custom sources.
`sort`	Optional	String	`recent`	Sort order: recent, top, trending.
`since`	Optional	ISO timestamp	`2024-01-15T00:00:00Z`	Return posts created after this timestamp.
`since_id`	Optional	String	`1879726815913861526`	Return posts created after this post id.
`limit`	Optional	Integer	`10`	Items per page (max 50).
`page`	Optional	Integer	`1`	Page number.

Data Points

Attribute	Parent Element	Type	Description
`id`	`items[]`	String	Native X post id.
`post_url`	`items[]`	String	Direct URL to the post on X.
`text`	`items[]`	String	Post body text.
`created_at`	`items[]`	ISO timestamp	Original post timestamp (UTC).
`media_type`	`items[]`	String	video \| photo \| gif \| animated_gif \| none
`media`	`items[]`	Array<MediaObject>	Attached media; see Media Object below.

Errors

Status	Code	Meaning & recommended action
400	INVALID_PARAMETER	Bad / missing param. Validate input before retrying.
400	SINCE_ID_NOT_FOUND	Reference post unavailable. Drop `since_id` and retry.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Endpoint or league not on your plan.
404	NOT_FOUND	No teams/players matched IDs.
429	RATE_LIMITED	Monthly limit / burst exceeded. Back off.
500	INTERNAL_ERROR	Retry with exponential backoff.

Try it out

Example Response

{
  "pagination": {
    "page": 1,
    "limit": 10,
    "has_next": true,
    "has_prev": false
  },
  "items": [
    {
      "id": "1879726815913861526",
      "post_url": "https://x.com/NFLonFOX/status/1879726815913861526",
      "text": "Patrick Mahomes throws his 3rd TD of the game! 🏈",
      "created_at": "2024-01-15T20:45:00Z",
      "media_type": "video",
      "media": [
        {
          "type": "video",
          "url": "https://video.twimg.com/...mp4",
          "preview_image_url": "https://pbs.twimg.com/...jpg",
          "width": 1280,
          "height": 720,
          "duration_ms": 24500
        }
      ],
      "author": {
        "username": "NFLonFOX",
        "name": "NFL on FOX",
        "profile_image_url": "https://pbs.twimg.com/profile_images/...jpg",
        "verified": true
      },
      "players": [
        {
          "espn_guid_id": "1f6592b3-ff53-d321-8dc5-6038d48c1786",
          "sportfeeds_id": 90000001,
          "name": "Patrick Mahomes"
        }
      ],
      "teams": [
        {
          "espn_guid_id": "s:20~l:28~t:12",
          "sportfeeds_id": 90000050,
          "name": "Kansas City Chiefs"
        }
      ]
    }
  ]
}

GET

/account/information

Free

Retrieve your company information, billing cycle, and current API usage. Free — call as often as needed.

Example Response

{
  "company": { "name": "Acme Sports Inc", "plan": "paid", "subscription_status": "active" },
  "billing_cycle": {
    "current_period_start": "2026-02-07T20:16:36+00:00",
    "current_period_end":   "2026-03-07T20:16:36+00:00"
  },
  "usage": { "current_calls": 12450 }
}

GET

/account/x-ids

Returns post IDs that should be deleted from your storage to remain compliant with the X platform's developer agreement. Recommended polling cadence depends on your plan (daily / weekly / monthly).

Example Response

{
  "ids_to_delete": ["1846572934857291245", "1846572934857291246"],
  "as_of": "2026-04-30T05:00:00Z"
}

GET

/ids

One endpoint for all ID lookups. Pass entity to choose teams, players, leagues, or posts.

Entity

List all teams in a league. Returned alphabetically by location. Auto-paginated up to 1,000 per call.

GET /ids?entity=teams&league=NFL&reference_id=sportradar_id

Parameters

Name	Type	Required	Description
entity	string	Yes	One of: teams, players, leagues, posts.
league	string	Yes	League code (NFL, NBA, MLB, NHL, PGA).
reference_id	string	No	External id column to include in each item. Response key matches the value you pass. Allowed: sportradar_id, espn_id, sportsdataio_id, nba_id, yahoo_dfs_id, apisports_id, grid_id, code, external_id.
lookup	string	No	Return only the single team matching this value (resolved against reference_id if provided, otherwise sportfeeds_id).

Example Response

{
  "ok": true,
  "count": 32,
  "items": [
    {
      "sportfeeds_id": 12000045,
      "location": "Atlanta",
      "name": "Falcons",
      "conference": null,
      "division": null,
      "league": "NFL",
      "sportradar_id": "e6aa13a4-0055-48a9-bc41-be28dc106929"
    }
  ]
}

SportFeeds API Documentation

Authorization

For AI Agents

/posts

Overview

Post Item

Author

Players & Teams

Pagination

Media Object

Try it out

Example Response

/account/information

/account/x-ids

/ids