Events

Unified endpoint for listing and searching events with filtering, pagination, and search.


GET /api/v1/events

This endpoint replaces the previous /schedule, /events/live, and /events/search endpoints. All functionality from those endpoints is now available here through query parameters. See Migration Notes below.

AuthenticationPermalink for this section

Requires API key via X-API-Key header, Authorization: Bearer header, or api_key query param. Available to all tiers.

Query ParametersPermalink for this section

Parameter	Type	Default	Description
`sport`	string	all	Filter by sport. Comma-separated for multiple (e.g., `basketball,football`)
`league`	string	all	Filter by league. Comma-separated for multiple (e.g., `nba,nfl`)
`sportsbook`	string	all	Filter by sportsbook (e.g., `draftkings,pinnacle`)
`live`	boolean	—	`true` = live only, `false` = prematch only, omit = both
`date`	string	—	Filter by date in `YYYY-MM-DD` format
`q`	string	—	Search query matching team names or event names
`limit`	integer	50	Results per page (max 200)
`offset`	integer	0	Pagination offset (max 5000)

Query parameters use singular form and comma-separated values for multiples: sport=basketball,football, not sports=basketball&sports=football.

Response HeadersPermalink for this section

All responses include standard rate limit and metadata headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your tier
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets
`X-Data-Delay`	Data delay for your tier (e.g., `0s`, `60s`)
`X-Request-Id`	Unique request identifier for debugging

Event ObjectPermalink for this section

Field	Type	Description
`id`	string	Canonical event identifier — the same for every sportsbook covering this event. Use as your primary key for cross-book matching. See Event Matching.
`uuid`	string	Stable canonical event UUID (feed-stable hash; useful for cross-feed joins).
`external_ids`	object	Map of sportsbook ID to that book’s native event ID (e.g., `{"draftkings": "33483153"}`). Use these for deep linking back to sportsbook pages.
`sport`	string	Sport identifier (e.g., `basketball`, `football`)
`league`	string	League slug (e.g., `nba`, `nfl`)
`home_team`	string	Home team name
`away_team`	string	Away team name
`start_time`	string	ISO 8601 event start time
`status`	string	Event status: `upcoming` or `live`
`is_live`	boolean	Whether the event is currently live
`book_count`	integer	Number of sportsbooks with odds for this event
`market_count`	integer	Number of distinct markets available for this event
`markets`	string[]	Sorted array of available market types (e.g., `["moneyline", "point_spread", "total_points"]`)
`books`	string[]	Sorted array of sportsbook IDs with odds for this event

Live scores/period/clock are not on event rows. Fetch live game state from the Game State endpoint (or the gamestate stream channel), joined by id.

Example RequestsPermalink for this section

List upcoming NBA and NFL eventsPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await response.json();
console.log(`Found ${pagination.total} events, showing ${pagination.count}`);

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'sport': 'basketball,football',
        'league': 'nba,nfl',
        'limit': 20
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()
print(f"Found {data['pagination']['total']} events")

Get live events onlyPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?live=true',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
console.log(`${data.length} live events`);

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'live': 'true'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
live_events = response.json()['data']

Search for a teamPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?q=celtics',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={'q': 'celtics'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
results = response.json()['data']

Filter by date and sportsbookPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/events',
    params={
        'date': '2026-02-08',
        'sportsbook': 'draftkings,fanduel'
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()

ResponsePermalink for this section

Success (200)Permalink for this section


{
  "data": [
    {
      "id": "nba_celtics_lakers_2026-02-08_b3",
      "uuid": "d4d5935357a21a1f",
      "external_ids": {
        "draftkings": "33483200",
        "fanduel": "nba-bos-lal-20260208"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Boston Celtics",
      "away_team": "Los Angeles Lakers",
      "start_time": "2026-02-08T19:30:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 6,
      "market_count": 14,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "caesars", "draftkings", "fanduel"]
    },
    {
      "id": "nba_heat_warriors_2026-02-08_b3",
      "uuid": "a1b2c3d4e5f60718",
      "external_ids": {
        "draftkings": "33483205"
      },
      "sport": "basketball",
      "league": "nba",
      "home_team": "Golden State Warriors",
      "away_team": "Miami Heat",
      "start_time": "2026-02-08T22:00:00Z",
      "status": "upcoming",
      "is_live": false,
      "book_count": 5,
      "market_count": 9,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "draftkings", "fanduel"]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 2,
    "total": 43,
    "has_more": true,
    "next_offset": 50
  },
  "updated_at": "2026-02-08T12:00:00Z"
}

Error ResponsesPermalink for this section

401 Unauthorized

No key supplied returns missing_api_key; a bad key returns invalid_api_key.


{
  "error": {
    "code": "missing_api_key",
    "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.",
    "docs": "https://sharpapi.io/docs/authentication"
  }
}

400 Bad Request

Returned only for malformed numeric parameters (non-numeric limit or offset):


{
  "error": {
    "code": "invalid_filter",
    "details": {
      "fields": {
        "limit": ["abc"]
      }
    },
    "message": "invalid filter values: limit=[abc]"
  }
}

An invalid date value (or any filter that matches nothing) is not rejected — it returns 200 with an empty result set. Note that an empty result serializes data as null, not [], with count: 0 and total: 0 in pagination.

429 Rate Limited


{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Upgrade your tier for higher limits.",
    "docs": "https://docs.sharpapi.io/en/pricing"
  }
}

Migration from Previous EndpointsPermalink for this section

Several legacy event sub-paths from earlier API versions are kept as deprecation signposts — hitting them returns 410 Gone with a machine-readable hint pointing at the correct endpoint.

Deprecated Path	Use Instead
`GET /events/search?q=celtics`	`GET /events?q=celtics`
`GET /events/list`	`GET /events`
`GET /events/all`	`GET /events`
`GET /events/find`	`GET /events`

410 Response ShapePermalink for this section


{
  "error": {
    "code": "unknown_endpoint",
    "message": "There is no /api/v1/events/search endpoint. Use GET /api/v1/events — results can be filtered with ?sport=, ?league=, and ?book= query parameters.",
    "correct_endpoint": "/api/v1/events",
    "docs": "https://docs.sharpapi.io/api-reference"
  }
}

Pre-v1 responses used camelCase field names (homeTeam, awayTeam, isLive, bookCount). The v1 API uses snake_case exclusively (home_team, away_team, is_live, book_count). Update your client code accordingly.

Key changes from previous versionsPermalink for this section

Field names are now snake_case (e.g., home_team instead of homeTeam)
Response uses the flat {data, pagination, updated_at} envelope instead of a top-level events array
Query parameters use singular form (sport instead of sports)
Base URL is https://api.sharpapi.io (not https://sharpapi.io)
Pagination now includes has_more and next_offset fields

Cross-Book Event MatchingPermalink for this section

The id field is a canonical event identifier — the same real-world event gets the same id regardless of which sportsbook it comes from. Use it as your primary key when building cross-book comparison tools. The external_ids field maps each sportsbook to its native event ID for deep linking.

See Event Matching for full details on how canonical IDs work.

Event Details - Get full details for a single event
Event Odds - Get all odds for a specific event
Event Markets - Get available markets for an event
Odds Snapshot - Get current odds across all events

Events

AuthenticationPermalink for this section

Query ParametersPermalink for this section

Response HeadersPermalink for this section

Event ObjectPermalink for this section

Example RequestsPermalink for this section

List upcoming NBA and NFL eventsPermalink for this section

cURL

JavaScript

Python

Get live events onlyPermalink for this section

cURL

JavaScript

Python

Search for a teamPermalink for this section

cURL

JavaScript

Python

Filter by date and sportsbookPermalink for this section

cURL

JavaScript

Python

ResponsePermalink for this section

Success (200)Permalink for this section

Error ResponsesPermalink for this section

Migration from Previous EndpointsPermalink for this section

410 Response ShapePermalink for this section

Key changes from previous versionsPermalink for this section

Cross-Book Event MatchingPermalink for this section

Related EndpointsPermalink for this section