Skip to content

Archive API (API v4)

Jump to bottom
Andrii Semchenko edited this page Jan 9, 2026 · 24 revisions

Archive API

All requests must be authenticated using an API key in the apiKey query parameter. Please contact your account manager to receive your personal API key.

We strongly recommend using gzip or deflate compression for all requests. It will reduce traffic usage and response time. To enable compression, add Accept-Encoding: gzip, deflate header to your requests. Before adding this header, make sure your HTTP client supports compression.

All endpoints have their own rate limits. If you exceed the limit, you will receive a 429 Too Many Requests response. These limits are individual for each API key. If you need to increase the limit, please contact your account manager.

Base URL

  • Live: https://api-lv.oddsmarket.org
  • Prematch: https://api-pr.oddsmarket.org

URL examples

  • https://api-lv.oddsmarket.org/v4/archive/events/search?apiKey=YOUR_API_KEY&...
  • https://api-pr.oddsmarket.org/v4/archive/events/search?apiKey=YOUR_API_KEY&...

Search Events

GET /v4/archive/events/search?apiKey=YOUR_API_KEY&sportIds=7,8&...
Parameter Description Type Required
sportIds List of Sport IDs SMALLINT[] No
leagueIds List of League IDs INT[] No
countryIds List of Country IDs SMALLINT[] No
startedFrom Filter by event start time (start, inclusive). Value should be in milliseconds since epoch (1715775441000) or formatted date time (2024-05-15T12:17:21Z) TIMESTAMP Yes
startedTo Filter by event start time (end, inclusive) TIMESTAMP Yes
requiredBookmakerIds List of Bookmaker IDs. Every event must have any data (odds, scores, etc.) from all of these BKs SMALLINT[] No
wantedBookmakerIds List of Bookmaker IDs. For an event to be selected for the result, at least minWantedBookmakersCount bookmakers from the wantedBookmakerIds list must have data (such as odds, scores, etc.) for this event SMALLINT[] No
minWantedBookmakersCount Minimum required number of bookmakers present in particular event from wantedBookmakerIds list INT No
minBookmakersCount Minimum required number of bookmakers present in particular event INT No
nameContains Filter by event name substring VARCHAR No
includeBookmakerIdsField Include bookmakerIds field in response. Default true BOOLEAN No
includePackedEvents Retrieve packed events (*) in response. Default false BOOLEAN No
lastEventId Last event ID from previous response. Used for pagination. BIGINT No
limit Maximum number of events in response. Default is 1000. Max is 10000. INT No

(*) Packed events are events which are stored in a long-term storage. Access to these events is slower and may be billed at a higher price. Events are packed after 180 days from the start date (this period may be changed in the future).

To fetch all events, you should use pagination. Send the first request with lastEventId parameter set to 0. Then use the last event ID from the response in the next request. Continue this process until the response is empty or hasMore field is false (it helps to avoid unnecessary requests).

By default, all events are sorted by start time in descending order. When you use pagination (lastEventId param i set), events are sorted by id in ascending order.

Maximum interval between startedFrom and startedTo is 180 days. If you need to fetch events for a longer period, you should split requests into several parts. Smaller intervals will reduce response time. Recommended interval is 30 days (1 month).

Response

{
  "events": [
    {
      "id": 63549641,
      "name": "Colon de Santa Fe - Los Andes",
      "homeId": 161,
      "awayId": 191,
      "sportId": 7,
      "leagueId": 3924,
      "startedAt": "2024-05-08T21:05:00Z",
      "eventType": 1,
      "bookmakersCount": 40,
      "packed": false,
      "bookmakerIds": [
        1,
        2,
      ]
    }
  ],
  "hasMore": true
}
Field Description Type
events List of Event objects Event[]
hasMore Indicates if there are more events available for the specified filters. Use for pagination (more information above) BOOLEAN

Event object

Field Description Type Example
id Event ID in our system BIGINT 63549641
name Event name VARCHAR "Colon de Santa Fe - Los Andes"
homeId Home team ID INT 161
awayId Away team ID INT 191
sportId Sport ID SMALLINT 7
leagueId League ID INT 3924
startedAt Event start time TIMESTAMP "2024-05-08T21:05:00Z"
eventType Event type SMALLINT 1
bookmakersCount Number of bookmakers with data for this event INT 40
packed Indicates if event is packed BOOLEAN false
bookmakerIds List of bookmaker IDs with data for this event (includeBookmakerIdsField must be set to true) SMALLINT[] [1, 2, ...]

Get Event By ID

Can be used to get metadata for a single event by ID. In addition to data from the search endpoint, it can include a list of bookmaker events, which contain IDs from a bookmaker and can be used to map your events to ours.

GET /v4/archive/events/{eventId}?apiKey=YOUR_API_KEY&includeBookmakerEventsField=true&bookmakerIds=1,2
Parameter Description Type Required
eventId Event ID in our system BIGINT Yes
includeBookmakerEventsField Include bookmakerEvents field in response. Default false BOOLEAN No
bookmakerIds Filter bookmakerEvents list in response by Bookmaker IDs SMALLINT[] No

Response

{
  "id": 63549641,
  "name": "Colon de Santa Fe - Los Andes",
  "homeId": 161,
  "awayId": 191,
  "sportId": 7,
  "leagueId": 3924,
  "startedAt": "2024-05-08T21:05:00Z",
  "eventType": 1,
  "bookmakersCount": 40,
  "packed": false,
  "bookmakerIds": [
    1,
    2,
  ],
  "bookmakerEvents": [
    {
      "id": 1,
      "rawId": "123",
      "directLink": "456"
    },
  ]
}

Root object is an Single event object.

Single event object

Field Description Type Example
id Event ID in our system BIGINT 63549641
name Event name VARCHAR "Colon de Santa Fe - Los Andes"
homeId Home team ID INT 161
awayId Away team ID INT 191
sportId Sport ID SMALLINT 7
leagueId League ID INT 3924
startedAt Event start time TIMESTAMP "2024-05-08T21:05:00Z"
eventType Event type SMALLINT 1
bookmakersCount Number of bookmakers with data for this event INT 40
packed Indicates if event is packed BOOLEAN false
bookmakerIds List of bookmaker IDs with data for this event SMALLINT[] [1, 2, ...]
bookmakerEvents List of BookmakerEvent objects (includeBookmakerEventsField must be set to true) BookmakerEvent[]

BookmakerEvent object

Field Description Type Example
id Bookmaker ID SMALLINT 1
rawId Unique identifier of event in a bookmaker system VARCHAR "123"
directLink Set of params and identifiers to reach an event in a bookmaker system. Should be parsed individually for every bookmaker. See DirectLink for details on formats and parsing. VARCHAR "456"
VARCHAR "789"

Get Multiple Events by IDs

Almost the same as the previous endpoint, but can be used to get metadata for multiple events by IDs. At the moment, bookmakerEvents field is not supported.

GET /v4/archive/events/multi?apiKey=YOUR_API_KEY&eventIds=63549641,63549642
Parameter Description Type Required
eventIds List of event IDs in our system BIGINT[] Yes

Number of IDs in the request is limited to URL length (4096 characters). If you need to fetch more events, you should split requests into several parts.

Response

[
  {
    "id": 63549641,
    "name": "Colon de Santa Fe - Los Andes",
    "homeId": 161,
    "awayId": 191,
    "sportId": 7,
    "leagueId": 3924,
    "startedAt": "2024-05-08T21:05:00Z",
    "eventType": 1,
    "bookmakersCount": 40,
    "packed": false,
    "bookmakerIds": [
      1,
      2,
    ]
  },
]

Root object is a list of Event objects.

Get Event Info

WARNING! You can only send one request at a time. If you send multiple requests simultaneously, you may receive an error response. This limitation can be extended by contacting your account manager.

GET /v4/archive/events/{eventId}/info?apiKey=YOUR_API_KEY&packed=false
Parameter Description Type Required
eventId Event ID in our system BIGINT Yes
packed Indicates if event is packed. You should use a value from a search response. Default false BOOLEAN No

It is important to use the packed value from the search response. If you use the wrong value, you will receive an empty response.

Response

{
  "bookmakerIds": [
    1,
    2,
  ],
  "betSpecs": [
    {
      "marketAndBetTypeId": 20,
      "marketAndBetTypeParam": 2.75,
      "periodIdentifier": 1,
      "lay": false,
      "playerId1": 0,
      "playerId2": 0
    },
  ]
}
Field Description Type
bookmakerIds List of bookmaker IDs with data for this event SMALLINT[]
betSpecs List of BetSpec objects BetSpec[]

BetSpec object

BetSpec is container for parameters which identify outcome within event.

Field Description Type Example
marketAndBetTypeId Market and bet type ID SMALLINT 20
marketAndBetTypeParam Market and bet type parameter FLOAT 2.75
periodIdentifier Period identifier SMALLINT 1
lay Indicates if it is a lay bet (true) or back bet (false) BOOLEAN false
playerId1 Player ID 1 INT 0
playerId2 Player ID 2 (specific markets only) INT 0

Get Bet Specs

WARNING! You can only send one request at a time. If you send multiple requests simultaneously, you may receive an error response. This limitation can be extended by contacting your account manager.

GET /v4/archive/events/{eventId}/bet-specs?apiKey=YOUR_API_KEY&bookmakerIds=1,2
Parameter Description Type Required
eventId Event ID in our system BIGINT Yes
bookmakerIds Filter results by bookmaker IDs (at least one must provide odds on a market) SMALLINT[] No
marketAndBetTypeIds Filter results by market and bet type IDs SMALLINT[] No
marketIds Filter results by Market IDs SMALLINT[] No
periodIdentifiers Filter results by period identifiers SMALLINT[] No
packed Indicates if event is packed. You should use a value from a search response. Default false BOOLEAN No

Response

{
  "bookmakers": {
    "1": {
      "betSpecs": [
        {
          "marketAndBetTypeId": 19,
          "marketAndBetTypeParam": 1.0,
          "periodIdentifier": 0,
          "lay": false,
          "playerId1": 0,
          "playerId2": 0
        },
      ]
    },
  }
}
Field Description Type
bookmakers Map from bookmaker ID to BookmakerBetSpecs object Map from SMALLINT to BookmakerBetSpecs

BookmakerBetSpecs object

Field Description Type
betSpecs List of BetSpec objects BetSpec[]

Get Timeline

WARNING! You can only send one request at a time. If you send multiple requests simultaneously, you may receive an error response. This limitation can be extended by contacting your account manager.

GET /v4/archive/events/{eventId}/timeline?apiKey=YOUR_API_KEY&bookmakerIds=1,2&betSpecs=20,2.75,1,0,0,0&betSpecs=21,1.5,1,0,0,0
Parameter Description Type Required
eventId Event ID in our system BIGINT Yes
bookmakerIds Filter results by bookmaker IDs. Max 10 bookmakers per request (*) SMALLINT[] Yes
betSpecs List of Bet Specs in the string format (marketAndBetTypeId,marketAndBetTypeParam,periodIdentifier,lay,playerId1,playerId2) VARCHAR[] No
startTimestamp Filter by timestamp (start, inclusive) BIGINT No
endTimestamp Filter by timestamp (end, inclusive) BIGINT No
packed Indicates if event is packed. You should use a value from a search response. Default false BOOLEAN No

* If you need to fetch more than 10 bookmakers, you should split requests into several parts.

Response

{
  "bookmakers": [
    {
      "bookmakerId": 11,
      "updates": {
        "deactivations": [
          1714442542091
        ],
        "scoreUpdates": [
          [
            1714434183222,
            "0:0"
          ]
        ],
        "cornersScoreUpdates": [
          [
            1714434661508,
            "0:0"
          ]
        ],
        "yellowCardsScoreUpdates": [
          [
            1714434661508,
            "0:0"
          ]
        ],
        "redCardsScoreUpdates": [
          [
            1714435203310,
            "0:0"
          ]
        ],
        "matchMinuteUpdates": [
          [
            1714434183222,
            0
          ]
        ],
        "matchPeriodUpdates": [
          [
            1714434183222,
            0
          ]
        ],
        "matchStatusUpdates": [
          [
            1714434362389,
            1
          ]
        ]
      },
      "bets": [
        {
          "betSpec": {
            "marketAndBetTypeId": 19,
            "marketAndBetTypeParam": 1.5,
            "periodIdentifier": 0,
            "lay": true,
            "playerId1": 0,
            "playerId2": 0
          },
          "koefUpdates": [
            [
              1714435442306,
              1.3333334
            ]
          ],
          "marketDepthUpdates": [
            [
              1714435442306,
              18.66
            ]
          ]
        }
      ]
    }
  ],
  "updates": {
    "scoreUpdates": [
      [
        1714434183222,
        "0:0"
      ]
    ],
    "cornersScoreUpdates": [
      [
        1714434661508,
        "0:0"
      ]
    ],
    "yellowCardsScoreUpdates": [
      [
        1714434661508,
        "0:0"
      ]
    ],
    "redCardsScoreUpdates": [
      [
        1714435203310,
        "0:0"
      ]
    ],
    "matchMinuteUpdates": [
      [
        1714434183222,
        0
      ]
    ],
    "matchPeriodUpdates": [
      [
        1714434183222,
        0
      ]
    ],
    "matchStatusUpdates": [
      [
        1714434362389,
        1
      ]
    ]
  }
}

Updates are sorted by timestamp in ascending order.

Field Description Type
bookmakers List of BookmakerTimeline objects. Contains updates of event in bookmaker systems BookmakerTimeline[]
updates EventTimelineUpdates object. Contains updates of event in our system EventTimelineUpdates

BookmakerTimeline object

Field Description Type
bookmakerId Bookmaker ID SMALLINT
updates EventTimelineUpdates object EventTimelineUpdates
bets List of BetTimeline objects BetTimeline[]

EventTimelineUpdates object

Field Description Type
deactivations List of timestamps when the bookmaker deactivated the event BIGINT[]
scoreUpdates List of [timestamp, score] pairs [BIGINT, VARCHAR][]
cornersScoreUpdates List of [timestamp, score] pairs [BIGINT, VARCHAR][]
yellowCardsScoreUpdates List of [timestamp, score] pairs [BIGINT, VARCHAR][]
redCardsScoreUpdates List of [timestamp, score] pairs [BIGINT, VARCHAR][]
matchMinuteUpdates List of [timestamp, minute] pairs [BIGINT, INT][]
matchPeriodUpdates List of [timestamp, periodIdentifier] pairs [BIGINT, SMALLINT][]
matchStatusUpdates List of [timestamp, status] pairs [BIGINT, TINYINT][]

BetTimeline object

Field Description Type
betSpec BetSpec object BetSpec
koefUpdates List of [timestamp, odds] pairs. The 0 odds value means that this outcome has been deactivated [BIGINT, FLOAT][]
marketDepthUpdates List of [timestamp, market depth] pairs [BIGINT, FLOAT][]

Get Closing Line Values (CLV) by Foreign IDs

WARNING! You can only send 5 requests at a time (concurrency limit). This limitation can be extended by contacting your account manager.

GET /v4/archive/events/clv_by_foreign_ids?apiKey=YOUR_API_KEY&rawIdOriginBookmakerId=1&rawEventId=E2423&rawBetIds=B34314&rawBetIds=B54314&bookmakerIds=2,3

OR

POST /v4/archive/events/clv_by_foreign_ids?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "rawIdOriginBookmakerId": 1,
  "rawEventId": "E2423",
  "rawBetIds": ["B34314", "B54314"],
  "bookmakerIds": [2, 3]
}
Parameter Description Type Required
rawIdOriginBookmakerId Bookmaker ID which is origin of rawEventId, rawBetId SMALLINT Yes
rawEventId Event ID at the IDs origin bookmaker VARCHAR Yes
rawBetIds Outcome ID at the IDs origin bookmaker. Max 10000 IDs per request (*) VARCHAR[] Yes
bookmakerIds Filter results by bookmaker IDs. Max 10 bookmakers per request (*) SMALLINT[] Yes
  • If you need to fetch more than 10 bookmakers or more than 10000 outcomes, you should split requests into several parts.

Response

{
  "B34314": {
    "bookmakers": {
      "2": {
        "eventId": 71230521,
        "betSpec": {
          "marketAndBetTypeId": 11,
          "marketAndBetTypeParam": 0.0,
          "periodIdentifier": 0,
          "lay": false,
          "playerId1": 0,
          "playerId2": 0
        },
        "lastKnownOdds": 1.031,
        "status": "DEACTIVATED",
        "lastModifiedAt": 1755962860962
      },
      "3": {
        "eventId": 71230521,
        "betSpec": {
          "marketAndBetTypeId": 11,
          "marketAndBetTypeParam": 0.0,
          "periodIdentifier": 0,
          "lay": false,
          "playerId1": 0,
          "playerId2": 0
        },
        "lastKnownOdds": 1.04,
        "status": "DEACTIVATED",
        "lastModifiedAt": 1755962856927
      }
    }
  },
  "B54314": {
    "bookmakers": {
      "2": {
        "eventId": 71230521,
        "betSpec": {
          "marketAndBetTypeId": 12,
          "marketAndBetTypeParam": 0.0,
          "periodIdentifier": 0,
          "lay": false,
          "playerId1": 0,
          "playerId2": 0
        },
        "lastKnownOdds": 12.0,
        "status": "DEACTIVATED",
        "lastModifiedAt": 1755962860962
      },
      "3": {
        "eventId": 71230521,
        "betSpec": {
          "marketAndBetTypeId": 12,
          "marketAndBetTypeParam": 0.0,
          "periodIdentifier": 0,
          "lay": false,
          "playerId1": 0,
          "playerId2": 0
        },
        "lastKnownOdds": 9.5,
        "status": "DEACTIVATED",
        "lastModifiedAt": 1755962856927
      }
    }
  }
}

Important notes:

  • In most cases eventId and betSpec are the same for all bookmakers for a given rawEventId and rawBetId, but it cannot be guaranteed. You should consider this when mapping your data or using these values in other API endpoints.
  • rawBetId may be absent in the response if the outcome does not exist in our system or if none of the specified bookmakers have data for this outcome.
  • If you need to get eventId and betSpec for a given rawEventId and rawBetId even if none of the specified bookmakers have data for this outcome, you should add rawIdOriginBookmakerId to the bookmakerIds list.

Response

Field Description Type
root object Map from rawBetId to OutcomeCLV object Map from VARCHAR to OutcomeCLV

OutcomeCLV object

Field Description Type
bookmakers Map from bookmaker ID to BookmakerOutcomeCLV object Map from SMALLINT to BookmakerOutcomeCLV

BookmakerOutcomeCLV object

Field Description Type
eventId Event ID in our system BIGINT
betSpec BetSpec object BetSpec
lastKnownOdds Last known odds value FLOAT
status Last known odds status Enumeration of (ACTIVE,DEACTIVATED,EXPIRED,UNRECOGNIZED)
lastModifiedAt Last odds modification time in milliseconds BIGINT

Get Opposite/Multi-Opposite Closing Line Values (CLV) by Foreign IDs

WARNING! You can only send 5 requests at a time (concurrency limit). This limitation can be extended by contacting your account manager.

GET /v4/archive/events/clv_multi_opposite_by_foreign_ids?apiKey=YOUR_API_KEY&rawIdOriginBookmakerId=193&rawEventId=BG-2475377&rawBetIds=BG-191941866:W2-1&bookmakerIds=335

OR

POST /v4/archive/events/clv_multi_opposite_by_foreign_ids?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "rawIdOriginBookmakerId": 193,
  "rawEventId": "BG-2475377",
  "rawBetIds": ["BG-191941866:W2-1"],
  "bookmakerIds": [335]
}
Parameter Description Type Required
rawIdOriginBookmakerId Bookmaker ID which is origin of rawEventId, rawBetId SMALLINT Yes
rawEventId Event ID at the IDs origin bookmaker VARCHAR Yes
rawBetIds Outcome ID at the IDs origin bookmaker. Max 10000 IDs per request (*) VARCHAR[] Yes
bookmakerIds Filter results by bookmaker IDs. Max 10 bookmakers per request (*) SMALLINT[] Yes
  • If you need to fetch more than 10 bookmakers or more than 10000 outcomes, you should split requests into several parts.

Response

{
  "BG-191941866:W2-1": {
    "bookmakers": {
      "335": {
        "eventId": 410062937,
        "odds": {
          "betSpec": {
            "marketAndBetType": 11,
            "marketAndBetTypeParam": 0.0,
            "periodIdentifier": 1,
            "isLay": false,
            "playerId1": 0,
            "playerId2": 0
          },
          "lastKnownOdds": 2.472,
          "status": "DEACTIVATED",
          "lastModifiedAt": 1766956393409
        },
        "oddsMultiOpposite": [
          {
            "betSpec": {
              "marketAndBetType": 13,
              "marketAndBetTypeParam": 0.0,
              "periodIdentifier": 1,
              "isLay": false,
              "playerId1": 0,
              "playerId2": 0
            },
            "lastKnownOdds": 2.811,
            "status": "DEACTIVATED",
            "lastModifiedAt": 1766956393409
          },
          {
            "betSpec": {
              "marketAndBetType": 12,
              "marketAndBetTypeParam": 0.0,
              "periodIdentifier": 1,
              "isLay": false,
              "playerId1": 0,
              "playerId2": 0
            },
            "lastKnownOdds": 4.17,
            "status": "DEACTIVATED",
            "lastModifiedAt": 1766956393409
          }
        ]
      }
    }
  }
}

Important notes:

  • In most cases eventId and betSpec are the same for all bookmakers for a given rawEventId and rawBetId, but it cannot be guaranteed. You should consider this when mapping your data or using these values in other API endpoints.
  • rawBetId may be absent in the response if the outcome does not exist in our system or if none of the specified bookmakers have data for this outcome.
  • If you need to get eventId and betSpec for a given rawEventId and rawBetId even if none of the specified bookmakers have data for this outcome, you should add rawIdOriginBookmakerId to the bookmakerIds list.

Response

Field Description Type
root object Map from rawBetId to OutcomeCLVMultiOpposite object Map from VARCHAR to OutcomeCLVMultiOpposite

OutcomeCLVMultiOpposite object

Field Description Type
bookmakers Map from bookmaker ID to BookmakerOutcomeCLVMultiOpposite object Map from SMALLINT to BookmakerOutcomeCLVMultiOpposite

BookmakerOutcomeCLVMultiOpposite object

Field Description Type
eventId Event ID in our system BIGINT
odds Direct odds data BetData object BetData
oddsOpposite Opposite odds (if applicable) data BetData object BetData
oddsMultiOpposite Array of BetData objects that represents all opposite outcomes odds data Array of BetData

BetData object

Field Description Type
betSpec BetSpec object BetSpec
lastKnownOdds Last known odds value FLOAT
status Last known odds status Enumeration of (ACTIVE,DEACTIVATED,EXPIRED,UNRECOGNIZED)
lastModifiedAt Last odds modification time in milliseconds BIGINT

This section describes API v4.

If you are using API v3 go to API v3 documentation root page.

Home

API Documentation

Websocket APIs - Realtime data

Odds feed WS API

Trading feed WS API

Events feed WS API

REST APIs - Realtime data

Datahealth endpoint

Arbs REST API

Getting Odds By Bet ID

BetsProtector REST API

Odds Comparison REST API

REST APIs - Historical data

Event Results REST API

Settlements REST API

Archive REST API

Final Scores REST API

Final Statuses REST API

REST dictionaries and support data types

MarketAndBetTypes

MarketAndBetType parameter

Markets

Outcome types

Opposite outcomes

Sports

Internal events

Countries

Leagues

Periods

Players

Teams

Bookmakers

Integration guidelines

Odds feed Java client

Trading feed integration for accepting bets

Client implementation best practices

FAQ

How to check the connection using a browser?

How do I know that the market is closed?

Quick start: How to use our data?

Other

Glossary and conventions

What's new in API v4 vs API v3

Clone this wiki locally