Update Frequencies

Intro

Each MLB API endpoint updates at a variable frequency, in terms of both its cache and its data.

For example, a Game endpoint may have a 3 second cache during a live game. Upon game close, it will transfer to a 600 second cache and after seven days, be updated to 4 hours. Alternatively, a Standings endpoint may have a 12 hour cache, but the data within will update when games conclude. And during the offseason, data will not update at all.

Given your limited amount of API requests and QPS, these frequencies should be understood and factored into your pull rate.

Use this section to help determine the best pull frequency for your needs.

Time-to-Live (TTL) and Data Updates

Understanding the distinction between TTL and data updates is crucial for designing an efficient and reliable MLB API solution. TTL is focused on the length of time an object cached, whereas data updates are concerned with the actual data within the API.

Time-to-Live (TTL)

Time-to-Live (TTL) defines the maximum duration a response may be served from cache before revalidation. TTL values are returned in the Cache-Control header for each REST feed. For example:

Cache-Control: public, must-revalidate, max-age=300

This indicates a TTL of 300 seconds.

TTL is an upper bound, not a guarantee. When underlying event data changes, our system proactively invalidates and replaces the cached object immediately, even if the TTL has not expired.

Data Updates

Data Updates refer to the changes made to the underlying data that the API provides access to. This can occur through various operations such as creating, updating, or deleting our sports data.

Data updates are critical to ensuring that the API delivers the most current and accurate information. Data entry workflows and processes specific to MLB data will affect your suggested request frequency.

Additional Frequency Resources

MLB API responses also provide expires and etag headers. Toggle between the two header samples below to get an idea of how each functions.

Expires

Use the expires header date to determine a specific time to re-fetch data. In cases, it may be more convenient than computing the date of the content alongside the TTL.

Etags

Use the etags header to check if the content has changed between requests.

< HTTP/2 200 
< content-type: application/xml;charset=utf-8
< content-length: 884005
< date: Wed, 03 Jul 2024 18:21:13 GMT
< x-amzn-requestid: 87355d21-5a20-429a-95e9-b36d406a992f
< strict-transport-security: max-age=15724800; includeSubDomains
< x-amzn-remapped-content-length: 884005
< content-language: en
< x-amzn-remapped-connection: close
< x-amz-apigw-id: aWR3wGSRIAMEddQ=
< cache-control: public, must-revalidate, max-age=120
< expires: Wed, 03 Jul 2024 18:23:12 GMT
< etag: "2b358d2fe60303e7bbd1be3d64a37cfe"
< x-via: Delivery-Proxy
< x-amzn-trace-id: Root=1-66859697-752ac4fa2c40a4586900aa76;Parent=667fb8ce9acca5af;Sampled=0;lineage=b9fe645c:0
< x-amzn-remapped-date: Wed, 03 Jul 2024 18:21:13 GMT
< via: 1.1 72b77c557ac4c265c32d99bdef4e9d6a.cloudfront.net (CloudFront), 1.1 d1b7c750b45b2751c2c1a34c2f5af9ec.cloudfront.net (CloudFront)
< x-amz-cf-pop: IAD79-C3
< vary: Accept-Encoding
< x-cache: Hit from cloudfront
< x-amz-cf-pop: ORD58-P6
< x-amz-cf-id: -u_iAJXYbBsYDq3ex20s2Sj7z0m-yIx5CDRpGHIPxz4k58-Pl-857A==
< age: 13

< HTTP/2 200 
< content-type: application/xml;charset=utf-8
< content-length: 884005
< date: Wed, 03 Jul 2024 18:32:17 GMT
< x-amzn-requestid: 0211fcbe-b272-49fc-9c2e-bc8c8fded090
< strict-transport-security: max-age=15724800; includeSubDomains
< x-amzn-remapped-content-length: 884005
< content-language: en
< x-amzn-remapped-connection: close
< x-amz-apigw-id: aWTfeFFkIAMEvvA=
< cache-control: public, must-revalidate, max-age=120
< expires: Wed, 03 Jul 2024 18:34:16 GMT
< etag: "94bf0a9737dd296c3ebf95f0b9de9ea5"
< x-via: Delivery-Proxy
< x-amzn-trace-id: Root=1-6685992f-41c8513b6c9423d36b717894;Parent=7c945e91890c1d79;Sampled=0;lineage=b9fe645c:0
< x-amzn-remapped-date: Wed, 03 Jul 2024 18:32:17 GMT
< via: 1.1 c3fbf93d9b0f1f9b36fcc420314f3186.cloudfront.net (CloudFront), 1.1 049d2c2e11b2a18bd6ce7ab8a5981ed2.cloudfront.net (CloudFront)
< x-amz-cf-pop: IAD79-C3
< vary: Accept-Encoding
< x-cache: Miss from cloudfront
< x-amz-cf-pop: ORD58-P6
< x-amz-cf-id: wjObvD9E5r97H03nJ95mPb1bmnnTOaLoLMtX9kOptCpyLqBQvz3Wpg==

League-Specific Headers

For league-specific APIs (including MLB), responses include the following headers that help distinguish cache behavior from true data freshness:

last-modified indicates when the versioned XML/JSON file in storage was last updated.
x-generated-date indicates when the underlying dataset was last generated or refreshed upstream, and is often the best indicator of data freshness.
x-cache indicates whether the response was served from the edge cache (Hit from CloudFront, Miss from CloudFront, etc.).

Frequency Chart

What is the right request frequency for your use? Which endpoints should you pull to get the most efficient use of your allotted calls?

The below chart provides answers to these questions, with a breakdown of the cache and data updates for every MLB API endpoint, as well as our recommended pulling frequency.

Endpoint	TTL / Cache	Data Updates	Recommended Pull (Non-Live)	Recommended Pull (Live)
Awards List	4 hours	Realtime	Pull every hour or less, depending on your use case.	Not applicable
Daily Boxscore	5 minutes for days with active games; 12 hours for days without active games	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 120 seconds (matching the TTL) when a game is live.
Daily Change Log	4 hours	Entries populate live for changes to teams, players, game statistics, schedules, and standings. Start time of the log is 10:00:00 UTC; end time is 09:59:59 UTC	Pull every ten minutes or less, depending on your use case.	Not applicable
Daily Schedule	600 seconds	Schedule info is updated in realtime as changes are made.	Pull every hour or less during the current day, depending on your use case.	Not applicable
Daily Summary	5 minutes for days with active games; 12 hours for days without active games	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 120 seconds (matching the TTL) when a game is live.
Daily Transactions	4 hours	Transactions update in realtime as they are entered.	Pull every hour or less, depending on your use case.	Not applicable
Event Tracking	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will transfer to 120s.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Free Agents	4 hours	Free agent records update in realtime as rosters or player profiles change.	Pull every hour or less, depending on your use case.	Not applicable
Game Boxscore	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will update to 600s. After seven days, the TTL will change to 4 hours.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Game Extended Summary	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will update to 600s. After seven days, the TTL will change to 4 hours.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Game Pitch Metrics	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will update to 600s. After seven days, the TTL will change to 4 hours.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Game Play-by-Play	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will update to 600s. After seven days, the TTL will change to 4 hours.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Game Summary	This endpoint will update to a 3s TTL (time to live) upon a game moving to `inprogress`. Upon `closed`, it will update to 600s. After seven days, the TTL will change to 4 hours.	Realtime	Pull on an as-needed basis. Feed can be ignored until 10 minutes before the scheduled game start, depending on your use case. Utilize the daily change log to capture data changes after a game has ended.	Can request as fast as every 2 seconds (matching the TTL) when a game is live. Game feeds should be requested 10 minutes before the scheduled start.
Glossary	4 hours	New data points and updates appear after development work is completed, often during the offseason.	Pull on an as-needed basis.	Not applicable
Injuries	4 hours	Injuries update based on the game day and the injury reporting workflow. See our Data Entry Workflow section for specific timings on injury updates.	Pull every hour or less, depending on your use case.	Not applicable
League Depth Chart	4 hours	Depth charts may update multiple times per week to remain current.	Pull every hour or less, depending on your use case.	Not applicable
League Hierarchy	4 hours	Hierarchy updates appear as they are updated in the database.	Pull daily or less, depending on your use case.	Not applicable
League Leaders	4 hours	League leaders update around 5 minutes after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to closed to receive the quickest updates
League Schedule	4 hours	Schedule info updates in realtime as changes are made.	Pull every hour or less, depending on your use case. Note that this feed should be used for schedule info prior to a game start. For status of a live game, reference a "game" endpoint.	Not applicable
Officials	4 hours	Officials update in realtime as profiles change.	Pull on an as-needed basis.	Not applicable
Player Profile	12 hours	Seasonal stats update on a 5-minute timer after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to 'closed' to receive the quickest updates
Rankings	12 hours	Rankings update nightly after all games finish. As the playoffs near, the `clinched` data point updates about 5 minutes after a game closes.	Pull every hour or less depending on your use case.	Pull 2-5 mins after a game is moved to 'complete' to receive the quickest updates
Seasonal Awards	12 hours	Realtime	Pull every hour or less, depending on your use case.	Not applicable
Seasonal Pitch Metrics	12 hours	Seasonal stats update on a 5-minute timer after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to 'closed' to receive the quickest updates
Seasonal Splits	12 hours	Seasonal stats update on a 5-minute timer after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to 'closed' to receive the quickest updates
Seasonal Statistics	12 hours	Seasonal stats update on a 5-minute timer after a game moves to `closed`	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to 'closed' to receive the quickest updates
Seasons	4 hours	New seasons appear as they are added to the database. Season status updates on the day it changes.	Pull on an as-needed basis.	Not applicable
Series Schedule	5 minutes for series' with active games, 12 hours for series' without active games.	Schedule info updates in realtime as changes are made. The initial playoff schedule (with TBD matchups) will be available in August.	Pull on an as-needed basis.	Pull every hour or less, depending on your use case. Note that this feed should be used for schedule info prior to a game start. For status of a live game, reference a "game" endpoint.
Series Statistics	4 hours	Series stats update around 5 minutes after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to closed to receive the quickest updates
Series Summary	4 hours	Series summary updates around 5 minutes after a game moves to `closed`.	Pull on an as-needed basis. Utilize the daily change log to capture data changes after a game has ended.	Pull 5-10 mins after a game is moved to closed to receive the quickest updates
Standings	12 hours	Standings update within 2 minutes of each game moving to `complete`.	Pull every hour or less, depending on your use case.	Pull 2-5 mins after a game is moved to `complete` to receive the quickest updates
Statcast Leaders	12 hours	Statcast leaders update once daily at the beginning of each day.	Pull on an as-needed basis.	Not applicable
Team Depth Chart	4 hours	Depth charts may update multiple times per week to remain current.	Pull every hour or less, depending on your use case.	Not applicable
Team Profile	4 hours	Team profiles update in realtime as rosters or player profiles change.	Pull every hour or less, depending on your use case.	Not applicable
Team	4 hours	New teams appear as they are added to the database.	Pull on an as-needed basis.	Not applicable
Venues	4 hours	Venues update in realtime as venue details change.	Pull on an as-needed basis.	Not applicable

⚾
Important Note
Pull recommendations are based on a typical customer's needs. We suggest starting with our recommended rate and adjusting as necessary according to your needs.