API Basics

This page covers the practical basics of the Global Baseball API: authentication, URL structure, formats and languages, pagination, errors, and cache behavior. The payloads themselves are covered in Fundamentals and the scenario pages.

Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/baseball/trial/v2/en/competitions.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URL and URL Structure

All requests follow one URL shape:

GET https://api.sportradar.com/{sport}/{access_level}/v2/{language_code}/{feed}.{format}

• sport: baseball or softball. The two sports share the same API; switching this one segment switches every feed to softball competitions.
• access_level: trial or production, matching your key.
• language_code: en, es, ja, ko, zh, or zht are the fully supported languages. For per-competition language availability, consult the supported languages sheet.
• format: json or xml. Both carry the same data on every feed.

The Probabilities package uses its own base path, https://api.sportradar.com/baseball-probabilities/, with the same placeholders and no sport segment; see Tracking Win Probabilities.

Pagination

List-heavy feeds page with start and limit query parameters (offset is accepted as an alternative to start) and report their totals in the X-Max-Results, X-Offset, and X-Result response headers. Page sizes differ by feed: Season Summaries, Daily Summaries, and the change feeds page at up to 200; Season Players at up to 800; Season Competitors and the mapping feeds at up to 1,000; Season Lineups at up to 100.

A season of MLB games spans multiple pages. This request, executed live, returned games 201 through 400 of the 2026 season:

GET https://api.sportradar.com/baseball/trial/v2/en/seasons/sr:season:134469/summaries.json?start=200&limit=200
x-api-key: YOUR_API_KEY

Walk start in steps of limit until a page returns fewer than limit rows, or until X-Offset plus X-Result reaches X-Max-Results.

Errors

• Authentication failures return 403 with an HTML page, not a JSON or XML error object; branch on the status code:

      <!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="utf-8">
          <title>Authentication Error</title>
        </head>
        <body>
          <p>Authentication Error</p>
        </body>
      </html>

• Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts
• 404 indicates an unknown ID or path
• Other statuses follow the Response Codes page

Cache Behavior

Each response carries a cache-control header stating how long the payload may be served from cache. TTLs range from 1 second on the live and probability feeds to 5 minutes on the discovery and profile feeds; the per-feed chart, with data update cadences and recommended polling, is on the Update Frequencies page.

Time Values

All timestamps are UTC ISO 8601 (start_time values carry an explicit offset). Date-scoped feeds such as Daily Summaries use the UTC date, so a US evening slate lands on the following UTC date: plan date math accordingly.

Integration Resources

• OpenAPI specifications: core API and probabilities package, with parameters, schemas, and enumerations per endpoint
• XSD schema: the Global Baseball v2 schema bundle for XML consumers
• Postman: a public collection for exploring the feeds interactively
• Coverage: the Coverage Matrix shows per-competition coverage; each season's own coverage block (see Fundamentals) is the in-API statement