> ## Documentation Index > Fetch the complete documentation index at: https://docs.fieldfunded.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Events Batch > Fetch full details for up to 20 events in a single request. More efficient than individual requests. Returns **400 Bad Request** if more than 20 IDs are provided. **Full Market Depth**: Each event in the batch response contains the **same complete market data** as `/v1/events/{eventId}` — up to 1,000+ markets per event on major leagues (NBA, NFL, Premier League). There is no market capping or reduction in batch mode. **Performance Advisory**: Batching 20 market-heavy events (e.g., live NBA games with 700+ selections each) can produce very large response payloads (5-15 MB+). For optimal performance: - Use smaller batch sizes (5-10 IDs) when fetching market-intensive events - Use `/v1/scores` for lightweight status polling (no markets), then batch-fetch only the events you need full odds for - Use `/v1/events/{eventId}` for single-event deep dives ## OpenAPI ````yaml POST /v1/events/batch openapi: 3.0.3 info: title: FieldFunded Sports API description: > Real-time sports data API covering **30+ sports & esports** and **1,000+ betting markets** per event. Built for low-latency live odds, settlement, and quantitative analysis. ## Official SDK The fastest way to integrate is using our official [TypeScript SDK](/sdk). It handles authentication, retries, and provides full type safety for all 1,000+ markets. ## Features - **Sub-second latency** — Data refreshed every 300ms from live feeds - **30+ sports & esports** — Soccer, Basketball, Tennis, Ice Hockey, Baseball, American Football, Rugby, Cricket, MMA, Handball, Volleyball, and more - **Full Esports Coverage** — Counter-Strike, Dota 2, LoL, Valorant, Rainbow Six, King of Glory, Call of Duty, Mobile Legends - **1,000+ Markets per game** — Match Winner, Over/Under, BTTS, Handicaps, Corners, Cards, Player Props, Map Winner, Round Winner, and more (major leagues like NBA, NFL, Premier League) - **Live Scores** — Real-time scoreboards with period scores, serving indicators, and match clocks - **Outrights/Futures** — Long-term futures and season-level markets (e.g., League Winner, Top Goalscorer, Most Assists, Tournament MVP) - **Settlement Results** (Automatic) — Per-market settlement outcomes (won/lost/refund) for ended events, with gradual market-by-market resolution. No developer action required — markets begin resolving within seconds after game end. Send `stake` to get instant `payout` calculation (currency-agnostic). Poll regularly after the game ends to capture all market resolutions as they arrive. - **Parlay Resolution** (Exclusive) — Submit multi-leg parlays (singles, combos) and get combined result + payout calculation with optional `stake`. Refund legs are treated as odds 1.00 in the combined calculation. - **Featured Games** — Curated top matches from priority leagues (Premier League, La Liga, Champions League, Europa League, Bundesliga, Serie A, Ligue 1, NBA, NFL, MLB, NHL), live-first sorted. - **Rich Visual Assets** — PNG team logos (~85% coverage), PNG & SVG team logos for featured leagues, SVG league logos, 182 SVG country flags and custom SVG sport icons. - **Global Coverage** — Premier League, La Liga, NBA, NFL, NHL, MLB, Champions League, and thousands of worldwide leagues including 3rd divisions, regional cups, ITF tournaments, and youth/female leagues, etc. ## Pricing Free tier with 10,000 requests/month. Paid plans from $29/mo. All features included at every tier. See [full pricing comparison](/compare/pricing). ## Learn More - [Quick Start Guide](/quickstart) — First API call in 5 minutes - [Authentication](/authentication) — API key setup - [Rate Limits](/rate-limits) — Per-plan limits and quota monitoring - [Supported Sports](/reference/supported-sports) — Full sport key reference - [Market Types](/reference/market-types) — 1,000+ market catalogue - [Event Statuses](/reference/event-statuses) — Lifecycle and 48-hour rule - [Visual Assets](/reference/visual-assets) — Logos, flags, and icons - [SDK Reference](/sdk) — TypeScript SDK installation and usage ## Sport-Specific Live Data Detail endpoints include a `sport_data` object with sport-specific fields: - **Tennis/Volleyball**: `home_serving`, `away_serving` (who is serving), `home_game_score`/`away_game_score` (values: `0`, `15`, `30`, `40`, `AD`), `is_tiebreak` - **Ice Hockey**: `home_suspend`/`away_suspend` (players in penalty box = power play indicator) - **All sports**: Period-by-period scoreboards via `scoreboard` object The `scoreboard` object contains: - `headers`: Column labels (e.g. `["", "1st", "2nd", "T", "Corner", "YC", "RC"]`) - `home`/`away`: Stats arrays matching the headers **Sport-specific scoreboard detail:** | Sport | Scoreboard Columns | Extra Fields | |-------|-------------------|--------------| | **Football (Soccer)** | 1st Half, 2nd Half, Total, Corners, Yellow Cards (YC), Red Cards (RC) | `period` (1H, 2H, HT, ET, PEN) | | **Tennis** | Set 1, Set 2, Set 3, Set 4, Set 5, Total | `home_game_score`/`away_game_score` (0, 15, 30, 40, AD), `is_tiebreak`, `home_serving`/`away_serving` | | **Basketball (NBA)** | Q1, Q2, Q3, Q4, OT, Total | `period` (Q1-Q4, OT1-OT3) | | **Ice Hockey (NHL)** | P1, P2, P3, OT, Total | `home_suspend`/`away_suspend` (power play) | | **American Football (NFL)** | Q1, Q2, Q3, Q4, OT, Total | `period`, `down_and_distance` | | **Baseball (MLB)** | Inn 1-9+, Total, Hits, Errors | `period` (Top/Bot 1-9+), `bases`, `outs` | | **Volleyball** | Set 1-5, Points, Total | `home_serving`/`away_serving` | | **Table Tennis** | Set 1-7, Total | `home_serving`/`away_serving` | | **CS2 / Valorant** | Map 1, Map 2, Map 3, Rounds | `current_map`, `map_score`, `round_score` | | **Dota 2 / LoL** | Game 1, Game 2, Game 3, Total | `current_game`, `game_duration` | | **Cricket** | Innings 1, Innings 2, Overs, Wickets | `run_rate`, `target` | | **Handball** | 1st Half, 2nd Half, Total | `period` | | **Rugby** | 1st Half, 2nd Half, Total | `period`, `try_count` | | **Darts** | Set/Leg scores | `current_set`, `current_leg` | | **Snooker** | Frame scores, Total | `current_frame`, `frame_score` | | **MMA / Boxing** | Round 1-12, Total | `current_round` | ## Prematch Odds - Prematch events include full market odds (up to 1,000+ markets per event on major leagues) - Odds are refreshed via incremental cursor — 10 prematch games per 300ms cycle (~10-30s full pass depending on total game count) - Detail data (markets, scoreboards) polled every ~16-20s per event - All odds formats supported: `decimal`, `american`, `fractional` ### Fixture Horizon Prematch fixture depth is **league-dependent** — major leagues (e.g. Premier League, NBA) typically appear further ahead than niche or regional events. There is no fixed global limit; it reflects when the data provider publishes upcoming matches. Use `GET /v1/events?starts_within=2h` or `starts_within=1d` to filter by time window. Every event includes a `commence_time` (ISO 8601) field for precise scheduling. ## Market Suspension & Locked Odds Individual selections or entire markets can become temporarily **locked** (`is_locked: true`). This happens during: - **Goal/score events** — markets lock for 30-60 seconds while odds are recalculated - **Dangerous moments** — e.g. penalty kicks, red cards, break points in tennis - **End of game** — as a match approaches final minutes, the provider progressively locks markets - **Half-time / period breaks** — some markets lock between periods When `is_locked: true`, the odds value is still present (last known value) but the selection **cannot be bet on**. Your UI should grey out or disable these selections. ### Empty Markets (End of Game) Near the end of a live match, the `markets` array may become **empty** (`[]`) or return with **all outcomes locked**. This is normal — the provider stops accepting bets in the final minutes. The `markets_count` field will reflect `0` in this case. After the game finishes (`status: "ended"`), markets are no longer returned. Use `/v1/events/{eventId}/result` or `/v1/settlements` for final settlement data. ### ended Game Snapshot (Endgame Data) When a game finishes (or is cancelled/postponed), the API archives the final score permanently and provides settlement data in a rolling window. This applies to **all sports & esports** (Soccer, NBA, CS2, LoL, Tennis, etc.). **Two tiers of post-game data:** | Endpoint | Data | Retention | |----------|------|-----------| | `/v1/events/{eventId}/result` | Final score, status | **Permanent** — archived indefinitely | | `/v1/settlements` | Market resolutions (won/lost/refund), team names, scores, logos | **Recent** — poll regularly after game end to capture all market resolutions as they arrive gradually | | `/v1/bets/check` | Bet resolution against settlement data | **Recent** (same as settlements) | > **Important**: Process settlements promptly by polling every 60 seconds. Final scores remain permanently available via `/v1/events/{eventId}/result`. ## Team Side Identification Market outcomes include an optional `team_side` field: - `"home"` — this selection refers to the home team - `"away"` — this selection refers to the away team - `null` or absent — neutral selection (Draw, Over/Under totals, etc.) This is useful for mapping selections to team names without parsing the `label` string. Available on 1X2, Handicap, Double Chance, and similar two-sided markets. ### Prematch → Live Transition Detected automatically. When a game kicks off, its status changes from `prematch` to `live` and it appears in `/v1/live`. No action needed from the developer. All IDs, scores, and timestamps in endpoint examples are **synthetic**. Use /v1/events to discover real event IDs. version: 1.0.0 termsOfService: https://docs.fieldfunded.com/terms contact: name: FieldFunded API Support url: https://docs.fieldfunded.com email: support@fieldfunded.com servers: - url: https://api.fieldfunded.com description: Production security: - ApiKeyAuth: [] tags: - name: Sports description: Discover available sports and leagues - name: Events description: Browse and search sports events - name: Live description: Real-time live event data and scores - name: Odds description: Current betting odds - name: Results description: Automatic match settlement and outcomes - name: Settlement description: > Fully automatic bet settlement — markets resolve on their own as soon as a game ends. No developer action required. Also includes bet-check endpoints: submit your users' selections to verify outcomes against automatic results. Supports single bets and multi-leg parlays/combos. The 48-hour rule applies: postponed/suspended games that don't resume within 48h are auto-refunded. #### Accurate Settlement Using IDs Every market and selection has a unique ID (`market_id` and `selection_id`). Use these IDs for bet placement and settlement to guarantee 100% accuracy. Market names and labels are also available for display purposes. - name: Outrights description: | Season-level winner markets (e.g., League Winner). Updated every 3 hours. - name: System description: API health and status - name: Usage Monitoring description: >- Track your API usage, quota status, and active warnings. Data available via the Developer Portal at `/portal`. paths: /v1/events/batch: post: tags: - Events summary: Batch Events — Full market depth for up to 20 events in one request description: > Fetch full details for up to 20 events in a single request. More efficient than individual requests. Returns **400 Bad Request** if more than 20 IDs are provided. **Full Market Depth**: Each event in the batch response contains the **same complete market data** as `/v1/events/{eventId}` — up to 1,000+ markets per event on major leagues (NBA, NFL, Premier League). There is no market capping or reduction in batch mode. **Performance Advisory**: Batching 20 market-heavy events (e.g., live NBA games with 700+ selections each) can produce very large response payloads (5-15 MB+). For optimal performance: - Use smaller batch sizes (5-10 IDs) when fetching market-intensive events - Use `/v1/scores` for lightweight status polling (no markets), then batch-fetch only the events you need full odds for - Use `/v1/events/{eventId}` for single-event deep dives operationId: getEventsBatch parameters: - name: odds_format in: query description: 'Odds format for all values in response. Default: decimal' schema: type: string enum: - decimal - american - fractional default: decimal requestBody: required: true content: application/json: schema: type: object required: - ids properties: ids: type: array items: type: string maxItems: 20 description: >- Array of event IDs (max 20). Use GET /v1/events to discover active IDs. responses: '200': description: >- A dictionary of comprehensive event details mapped by their respective event IDs. content: application/json: schema: type: object properties: events: type: object additionalProperties: $ref: '#/components/schemas/EventDetail' found: type: integer requested: type: integer example: events: '87654321': id: '87654321' sport: key: soccer name: Soccer league: slug: premier-league name: Premier League country: England home_team: Arsenal away_team: Chelsea home_logo: https://api.fieldfunded.com/api/logo/t-38 away_logo: https://api.fieldfunded.com/api/logo/t-42 status: live start_time: '2026-04-12T15:00:00Z' score: home: 2 away: 1 clock: '67:10' period: 2nd Half odds: home: 1.45 draw: 4.5 away: 6 odds_format: decimal markets_count: 72 markets: - key: 1x2 name: Match Winner outcomes: - label: Home odds: 1.45 updated_at: '2026-04-12T15:45:30.000Z' '87654322': id: '87654322' sport: key: soccer name: Soccer league: slug: la-liga name: La Liga country: Spain home_team: Real Madrid away_team: Barcelona home_logo: https://api.fieldfunded.com/api/logo/t-2829 away_logo: https://api.fieldfunded.com/api/logo/t-2817 status: prematch start_time: '2026-04-14T20:00:00Z' score: home: 0 away: 0 clock: null period: '' odds: home: 2.1 draw: 3.4 away: 3.5 odds_format: decimal markets_count: 350 markets: - key: 1x2 name: Match Winner outcomes: - label: Home odds: 2.1 updated_at: '2026-04-12T18:00:00.000Z' found: 2 requested: 3 '400': description: Invalid request body or more than 20 event IDs provided content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: EventDetail: allOf: - $ref: '#/components/schemas/Event' - type: object properties: scoreboard: type: object description: Detailed period-by-period scores properties: headers: type: array items: type: string home: type: array items: type: string away: type: array items: type: string markets: type: array items: $ref: '#/components/schemas/Market' sport_data: type: object description: Sport-specific live data properties: home_serving: type: boolean description: Tennis/Volleyball — home player is serving away_serving: type: boolean home_game_score: type: string description: Tennis — current game score (e.g. "40") nullable: true away_game_score: type: string nullable: true is_tiebreak: type: boolean description: Tennis — currently in a tiebreak home_suspend: type: integer description: Ice Hockey — home players in penalty box nullable: true away_suspend: type: integer nullable: true updated_at: type: string format: date-time Error: type: object properties: error: type: string description: Error type message: type: string description: Human-readable error message example: error: not_found message: Event not found. For historical results, use /v1/settlements. Event: type: object properties: id: type: string example: '87654321' sport: type: object properties: key: type: string name: type: string league: type: object properties: slug: type: string description: >- URL-friendly league identifier for filtering (e.g. 'premier-league') name: type: string country: type: string description: Country name (e.g. 'England', 'Spain'). home_team: type: string away_team: type: string home_logo: type: string format: uri description: >- PNG team logo URL. Most major teams have logos; returns a default placeholder when unavailable. away_logo: type: string format: uri description: >- PNG team logo URL. Most major teams have logos; returns a default placeholder when unavailable. status: type: string enum: - live - prematch - ended - delayed - postponed - cancelled - suspended - retired description: > Event status. `delayed` = past start time but not live (auto-detected). `postponed`/`suspended` trigger the 48-hour settlement timer. `cancelled` includes walkovers and abandoned games. start_time: type: string format: date-time nullable: true description: >- Scheduled start time in ISO 8601. May be null if the event date is unknown. score: $ref: '#/components/schemas/Score' clock: type: string nullable: true description: >- Current match time (e.g. "67:10 2nd half"). Returns `null` for sports without a running clock (tennis, darts, CS2, etc.). odds: type: object nullable: true description: >- Main market odds (1X2 summary). May be absent or null for events without main market odds. properties: home: type: number nullable: true draw: type: number nullable: true away: type: number nullable: true odds_format: type: string enum: - decimal - american - fractional description: >- Odds format used in this response. Only present when odds are included. period: type: string description: >- Current game period (e.g. '1st Half', '2nd Period', 'Set 3'). Empty string when not applicable. markets_count: type: integer description: Total number of available markets is_delayed: type: boolean description: >- True when the event is past its scheduled start_time but not yet live. Only present for delayed events. delay_minutes: type: integer description: >- Minutes since scheduled start_time. Only present when is_delayed is true. updated_at: type: string format: date-time description: ISO 8601 timestamp of when this event data was last polled/updated. Market: type: object properties: market_id: type: integer description: >- Unique identifier for the market. Use this as the primary key for accurate settlement. example: 36 key: type: string description: Normalized machine-readable key (secondary identifier). example: 1x2 name: type: string description: Human-readable display name. example: Match Winner outcomes: type: array items: $ref: '#/components/schemas/Outcome' Score: type: object description: >- Home/away goals or points. A value of `0` is a valid score (for example, 0-0) and is returned as numeric zero. properties: home: type: integer example: 2 away: type: integer example: 1 Outcome: type: object properties: selection_id: type: integer description: >- Unique identifier for the selection. Use this as the primary key for accurate settlement. example: 206301062 label: type: string description: Human-readable outcome label (secondary identifier). example: Home odds: oneOf: - type: number format: float - type: string example: 1.85 is_locked: type: boolean description: Whether this selection is currently suspended team_side: type: string nullable: true enum: - home - away - null description: > Which team this selection refers to. Present on 1X2, Handicap, and similar two-sided markets. `null` for neutral selections (Draw, Over/Under, etc.). example: home responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Invalid or missing API key. Visit docs.fieldfunded.com for access. RateLimited: description: Rate limit exceeded headers: Retry-After: description: Seconds until rate limit resets schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited message: Rate limit exceeded. Upgrade your plan for higher limits. InternalServerError: description: | Internal server error. Something went wrong on our end. Usually transient — please retry after a short delay. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: server_error message: Internal server error ServiceUnavailable: description: > Backend data store temporarily unavailable. The `Retry-After` header indicates how many seconds to wait before retrying. The `component` field identifies which service is degraded (`realtime_data` for live odds/scores, `historical_data` for settlements). headers: Retry-After: description: Recommended wait time in seconds before retrying schema: type: integer example: 30 content: application/json: schema: type: object properties: error: type: string example: service_unavailable message: type: string example: Data store temporarily unavailable component: type: string enum: - realtime_data - historical_data description: Which service is temporarily degraded example: realtime_data example: error: service_unavailable message: Data store temporarily unavailable component: realtime_data securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Your FieldFunded API Key ````