Events API

API reference

Events

Events are the games and bouts ParlayLedger tracks. Every odds and stats endpoint takes an eventId, and these endpoints are how you find it.

Every request needs your API key in the X-API-Key header and counts as one call against your monthly quota. See Authentication and Quotas and limits.

EndpointWhat it returns
GET /eventsList events
GET /events/:eventIdGet an event
GET /events/resolve/by-refResolve a provider id
GET /events/statusSeason status

List events

GEThttps://api.parlayledger.com/events

Every ParlayLedger event for a league on a calendar day. Use it to get the eventId the odds and stats endpoints take.

  • Auth X-API-Key header
  • Quota 1 call per request

Query parameters

  • leagueKeystringrequired

    League key, for example NFL, NCAAF, NBA, WNBA, NCAAB, WNCAAB, NHL, MLB, MLS, EPL or MMA.

  • datestring (YYYY-MM-DD)required

    Calendar day in UTC. Returns events whose startTime falls between 00:00:00 and 23:59:59 UTC that day, earliest first.

Request

curl "https://api.parlayledger.com/events?leagueKey=NBA&date=2026-10-21" \
  -H "X-API-Key: $PARLAYLEDGER_API_KEY"

Response 200 application/json

200 OK
[
  {
    "id": "3f6c2a9e-8d1b-4e7a-9c55-1b2d4e6f8a10",
    "sportKey": "basketball",
    "leagueKey": "NBA",
    "season": "2026",
    "startTime": "2026-10-21T23:30:00.000Z",
    "status": "scheduled",
    "homeTeamId": "c1a9f6e2-4b7d-4e30-9a85-2f6d1b3c7e94",
    "awayTeamId": "9e4b2d7a-6c1f-4a58-b3e0-7d2a5c9f1b68",
    "homeTeamName": "Boston Celtics",
    "awayTeamName": "New York Knicks",
    "displayName": null,
    "stage": null,
    "week": null,
    "venueName": "TD Garden",
    "venueCity": "Boston",
    "meta": null,
    "createdAt": "2026-10-14T06:00:12.381Z",
    "updatedAt": "2026-10-21T06:00:09.114Z"
  }
]

Errors

  • 400leagueKey is required
  • 400date is required (YYYY-MM-DD)
  • 401Valid X-API-Key required
  • 429Monthly API quota exceeded

Get an event

GEThttps://api.parlayledger.com/events/:eventId

One event by its ParlayLedger id, with its current status.

  • Auth X-API-Key header
  • Quota 1 call per request
Note:

status is one of scheduled, live, final, cancelled or postponed.

Path parameters

  • eventIdstring (UUID)required

    ParlayLedger event id, from GET /events or GET /stats/events.

Request

curl "https://api.parlayledger.com/events/3f6c2a9e-8d1b-4e7a-9c55-1b2d4e6f8a10" \
  -H "X-API-Key: $PARLAYLEDGER_API_KEY"

Response 200 application/json

200 OK
{
  "id": "3f6c2a9e-8d1b-4e7a-9c55-1b2d4e6f8a10",
  "sportKey": "basketball",
  "leagueKey": "NBA",
  "season": "2026",
  "startTime": "2026-10-21T23:30:00.000Z",
  "status": "scheduled",
  "homeTeamId": "c1a9f6e2-4b7d-4e30-9a85-2f6d1b3c7e94",
  "awayTeamId": "9e4b2d7a-6c1f-4a58-b3e0-7d2a5c9f1b68",
  "homeTeamName": "Boston Celtics",
  "awayTeamName": "New York Knicks",
  "displayName": null,
  "stage": null,
  "week": null,
  "venueName": "TD Garden",
  "venueCity": "Boston",
  "meta": null,
  "createdAt": "2026-10-14T06:00:12.381Z",
  "updatedAt": "2026-10-21T06:00:09.114Z"
}

Errors

  • 404Event not found: <eventId>
  • 401Valid X-API-Key required
  • 429Monthly API quota exceeded

Resolve a provider id

GEThttps://api.parlayledger.com/events/resolve/by-ref

Map an upstream provider's event id to the ParlayLedger eventId. eventId is null when there is no match.

  • Auth X-API-Key header
  • Quota 1 call per request

Query parameters

  • providerstringrequired

    Upstream source name, for example collegebasketballdata_ncaab or api_sports_nba.

  • externalIdstringrequired

    The event's id at that provider.

Request

curl "https://api.parlayledger.com/events/resolve/by-ref?provider=collegebasketballdata_ncaab&externalId=12345" \
  -H "X-API-Key: $PARLAYLEDGER_API_KEY"

Response 200 application/json

200 OK
{
  "provider": "collegebasketballdata_ncaab",
  "externalId": "12345",
  "eventId": "3f6c2a9e-8d1b-4e7a-9c55-1b2d4e6f8a10"
}

Errors

  • 400provider is required
  • 400externalId is required
  • 401Valid X-API-Key required
  • 429Monthly API quota exceeded

Season status

GEThttps://api.parlayledger.com/events/status

Where each league is in its season: idle, upcoming or ongoing, with the season start and end dates, refreshed once a day. The body is null until the first refresh has run.

  • Auth X-API-Key header
  • Quota 1 call per request
Note:

Event-based leagues such as MMA have no season window, so they always read ongoing with null dates.

Request

curl "https://api.parlayledger.com/events/status" \
  -H "X-API-Key: $PARLAYLEDGER_API_KEY"

Response 200 application/json

200 OK
{
  "NFL": {
    "status": "ongoing",
    "startDate": "2026-09-10T00:00:00.000Z",
    "endDate": "2027-02-14T00:00:00.000Z"
  },
  "NBA": {
    "status": "ongoing",
    "startDate": "2026-10-20T00:00:00.000Z",
    "endDate": "2027-06-20T00:00:00.000Z"
  },
  "WNBA": {
    "status": "idle",
    "startDate": "2026-05-08T00:00:00.000Z",
    "endDate": "2026-10-12T00:00:00.000Z"
  },
  "MMA": {
    "status": "ongoing",
    "startDate": null,
    "endDate": null
  }
}

Errors

  • 401Valid X-API-Key required
  • 429Monthly API quota exceeded