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.

Authentication

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

Query Parameters

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
`has_score`	boolean	—	`true` = only events with live game state/scores
`date`	string	—	Filter by date in `YYYY-MM-DD` format
`team`	string	—	Filter by team name (partial match, case-insensitive, supports aliases like `lakers`)
`q`	string	—	Search query matching team names or event names
`limit`	integer	50	Results per page (max 500)
`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 Headers

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 Object

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.
`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
`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
`game_state`	object \| undefined	Live game state (only present for live events with scores)

Game State Object

Included when the event is live and has score data:

Field	Type	Description
`home_score`	number	Home team score
`away_score`	number \| null	Away team score
`period`	string \| null	Current period (e.g., `Q3`, `2nd`, `3rd Period`)
`clock`	string \| null	Time remaining (e.g., `5:42`)
`score_type`	string	Score type (e.g., `game_points`, `match`)
`possession`	string \| null	Team with possession (`home` or `away`)
`is_timeout`	boolean \| null	Whether a timeout is in progress
`power_play`	string \| null	Power play info (`home` or `away`, hockey)
`last_play`	string \| null	Description of last play

Example Requests

List upcoming NBA and NFL events

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, meta } = await response.json();
console.log(`Found ${meta.total} events, showing ${meta.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['meta']['total']} events")

Get live events only

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 team

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 sportsbook

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, meta } = 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()

Response

Success (200)


{
  "data": [
    {
      "id": "evt_nba_bos_lal_20260208",
      "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,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "caesars", "draftkings", "fanduel"]
    },
    {
      "id": "evt_nba_gsw_mia_20260208",
      "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,
      "markets": ["moneyline", "point_spread", "total_points"],
      "books": ["betmgm", "draftkings", "fanduel"]
    }
  ],
  "meta": {
    "count": 2,
    "total": 43,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50
    },
    "updated_at": "2026-02-08T12:00:00Z",
    "filters": {
      "sport": ["basketball"],
      "league": ["nba"]
    }
  }
}

Error Responses

401 Unauthorized


{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "docs": "https://sharpapi.io/docs/authentication"
  }
}

400 Bad Request


{
  "error": {
    "code": "invalid_request",
    "message": "Invalid date format. Use YYYY-MM-DD.",
    "docs": "https://sharpapi.io/docs/api-reference/events"
  }
}

429 Rate Limited


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

Migration from Previous Endpoints

This endpoint consolidates four previous endpoints into one:

Old Endpoint	New Equivalent
`GET /schedule`	`GET /events`
`GET /schedule/live`	`GET /events?live=true`
`GET /events/live`	`GET /events?live=true`
`GET /events/search?q=celtics`	`GET /events?q=celtics`

The previous endpoints 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 versions

Field names are now snake_case (e.g., home_team instead of homeTeam)
Response uses the standard data/meta envelope instead of 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 Matching

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

Authentication

Query Parameters

Response Headers

Event Object

Game State Object

Example Requests

List upcoming NBA and NFL events

cURL

JavaScript

Python

Get live events only

cURL

JavaScript

Python

Search for a team

cURL

JavaScript

Python

Filter by date and sportsbook

cURL

JavaScript

Python

Response

Success (200)

Error Responses

Migration from Previous Endpoints

Key changes from previous versions

Cross-Book Event Matching

Related Endpoints