BDL LAB Documentation

Overview

What is BDL Lab?

BDL Lab is a betting model builder by BALLDONTLIE. It allows you to create prediction models by combining pre-built factors, backtest against 6+ years of historical data, and track live predictions for upcoming games.

Key Features

• Factor-based modeling - Combine 15-18 pre-built factors per sport
• Historical backtesting - Test models against data from 2020 to present
• Multiple sports - NBA, NFL, NHL, and MLB supported
• Live predictions - Generate predictions for upcoming games
• API access - Programmatic access for automation and AI agents

Who is it for?

BDL Lab is designed for sports bettors who want a data-driven approach to their betting strategy. Whether you're a casual bettor looking to make more informed decisions or a serious bettor building systematic models, Lab provides the tools you need.

Subscription Tiers

Getting Started

1. Create an Account

Sign up for free at lab-app.balldontlie.io/signup. You can explore the UI and create models immediately with the free tier.

2. Choose Your Sport

Select from NBA, NFL, NHL, or MLB. Each sport has its own set of factors tailored to that league's unique characteristics.

3. Create Your First Model

1. Click Create Model on the Models page
2. Select a bet type (Spread, Moneyline, or Over/Under)
3. Choose your mode (Simple or Weighted)
4. Add factors and assign importance levels
5. Click Run Preview to see historical performance
6. Save your model when satisfied

4. Evaluate and Generate Predictions

After saving, run Evaluate Performance to get a full historical analysis. Then use Generate Predictions to create predictions for upcoming games.

Core Concepts

Factors

Factors are metrics that predict game outcomes. Each factor has a raw value (the actual metric) and a normalized score (0-100 scale) for comparison across different factors.

There are 5 factor categories:

• Team Performance - Scoring averages, defensive ratings, home/away splits
• Matchup - Head-to-head history, pace differentials
• Situational - Rest days, travel, schedule density
• Player - Star player availability and impact
• Market - Line movement, public betting percentages

Models

Models combine multiple factors with assigned weights to generate predictions. There are two modes:

• Simple Mode - Assign Low/Medium/High importance to each factor. The system converts these to weights automatically.
• Weighted Mode - Assign precise percentage weights that must sum to 100%.

Bet Types

• Point Spread - Predict which team covers the spread
• Moneyline - Predict the outright winner
• Over/Under - Predict whether total score goes over or under the line

Evaluation Pipeline

The workflow for using a model:

1. Preview - Test configuration before saving (results not persisted)
2. Save - Persist the model configuration
3. Evaluate - Run full historical analysis (results persisted)
4. Generate Predictions - Create predictions for upcoming games

Complete Walkthrough

This section walks through a complete example: creating an NBA spread model, running a backtest, interpreting results, and generating predictions. We'll explain every configuration choice along the way.

Step 1: Create the Model

Let's build a model called "NBA Rest & Defense" that focuses on situational advantages and defensive performance—two factors that tend to be undervalued by casual bettors.

Choosing the Sport and Bet Type

We're choosing NBA because basketball has the most games (82 per team) giving us the largest sample size for backtesting. Point spread is ideal because:

• Spreads require a more nuanced edge than moneyline (where heavy favorites offer little value)
• The vig on spreads (-110) is lower than moneyline underdogs
• Our factors (rest, defense) directly impact margin of victory, not just win/loss

Choosing the Mode

We'll use Simple Mode with Low/Medium/High importance levels. This is recommended when:

• You're still learning which factors work best
• You want the system to normalize weights automatically
• You prefer faster iteration over precise control

Weighted Mode (precise percentages) is better once you've identified your core factors through backtesting.

Selecting Factors

We'll select 5 factors, chosen to complement each other without overlap:

Configuration Summary

Model Name: NBA Rest & Defense
Sport: NBA
Bet Type: Point Spread
Mode: Simple

Factors:
  - team_last_n_pts_allowed_avg: HIGH (50)
  - rest_days:                   HIGH (50)
  - back_to_back:                MEDIUM (30)
  - team_ats_record:             MEDIUM (30)
  - travel_context:              LOW (10)

Total multiplier sum: 170
Effective weights:
  - team_last_n_pts_allowed_avg: 29.4%
  - rest_days:                   29.4%
  - back_to_back:                17.6%
  - team_ats_record:             17.6%
  - travel_context:              5.9%

Step 2: Run Preview

Before saving, click Run Preview to see how this model would have performed. The preview runs against all historical games with available odds.

Sample Preview Results

Historical Performance (2020-2024)
══════════════════════════════════
Total Games Analyzed: 4,892
Games with Predictions: 3,156 (64.5%)

Record: 1,672 - 1,412 - 72 (W-L-P)
Win Rate: 54.2%
ROI: +3.8%

Results by Confidence:
  Low (0-33):    512-498   (50.7%, +0.2% ROI)
  Medium (34-66): 724-612   (54.2%, +3.1% ROI)
  High (67-100):  436-302   (59.1%, +8.4% ROI)

How to Interpret Preview Results

Win Rate (54.2%):

• Against the spread, you need ~52.4% to break even (due to -110 vig)
• 54.2% is a solid edge—approximately +3.8% ROI assuming flat betting
• This means for every $100 wagered, you'd profit $3.80 on average

Results by Confidence:

• Low confidence (0-33): 50.7% is near break-even. These are games where the model has weak signal—consider skipping these.
• Medium confidence (34-66): 54.2% with +3.1% ROI. Decent edge but not overwhelming.
• High confidence (67-100): 59.1% with +8.4% ROI. This is where the model shines. The higher the confidence, the stronger the signal.

Games with Predictions (64.5%):

The model only predicts when the score differential exceeds the betting threshold (default: 5). 35.5% of games didn't meet this threshold—that's intentional. It's better to skip marginal games.

Key Insight: Focus on High Confidence

Step 3: Save and Evaluate

If the preview looks good, click Save Model. Then run Evaluate Performanceto persist the results.

Evaluation provides the same metrics as preview, but the results are saved so you can track them over time. It also provides additional breakdowns:

• Monthly performance - See how the model performs in different months (playoffs vs regular season)
• Per-game details - Review individual predictions and outcomes

Sample Evaluation Detail View

Date       | Matchup              | Line  | Prediction | Confidence | Result
───────────┼──────────────────────┼───────┼────────────┼────────────┼────────
2024-01-15 | BOS @ MIA            | -4.5  | BOS -4.5   | 72         | WIN
2024-01-15 | LAL @ DEN            | +7    | DEN -7     | 58         | LOSS
2024-01-14 | PHX @ GSW (B2B)      | +3    | GSW -3     | 81         | WIN
2024-01-14 | MIL @ CLE            | +2.5  | CLE -2.5   | 45         | PUSH
2024-01-13 | NYK @ BKN            | -6    | NYK -6     | 63         | WIN

Reading the breakdown:

• Line - The opening spread. Negative = home favorite.
• Prediction - Which side the model recommends.
• Confidence - Score from 0-100. Higher = stronger signal.
• Result - WIN (covered), LOSS (didn't cover), or PUSH (exactly on the number).

Notice the PHX @ GSW game: Phoenix was on a back-to-back, GSW was well-rested, and our model correctly predicted Golden State to cover at home. The 81 confidence reflects the strong situational advantage.

Step 4: Generate Predictions

Click Generate Predictions to create predictions for upcoming games. The system calculates current factor values and applies your model weights.

Sample Predictions Output

Upcoming Games - January 20, 2025
═════════════════════════════════

Game: Boston Celtics @ Miami Heat
  Line: BOS -3.5
  Prediction: BOSTON -3.5
  Confidence: 67 (HIGH)

  Factor Breakdown:
    pts_allowed_avg: BOS 106.2 (score: 78) vs MIA 112.4 (score: 45)
    rest_days:       BOS 2 days (score: 70) vs MIA 1 day (score: 50)
    back_to_back:    Neither team
    ats_record:      BOS 58% (score: 58) vs MIA 48% (score: 48)
    travel_context:  BOS road trip game 2 (score: 45) vs MIA home (score: 65)

  Model Scores: BOS 65.2, MIA 51.4 (diff: +13.8)

─────────────────────────────────

Game: Los Angeles Lakers @ Denver Nuggets
  Line: LAL +6.5
  Prediction: DENVER -6.5
  Confidence: 74 (HIGH)

  Factor Breakdown:
    pts_allowed_avg: LAL 115.8 (score: 32) vs DEN 108.4 (score: 68)
    rest_days:       LAL 0 days (score: 20) vs DEN 2 days (score: 70)
    back_to_back:    LAL is B2B (score: 40 vs 60)
    ats_record:      LAL 45% (score: 45) vs DEN 55% (score: 55)
    travel_context:  LAL road trip game 4 (score: 35) vs DEN home (score: 65)

  Model Scores: DEN 63.8, LAL 34.4 (diff: +29.4)

─────────────────────────────────

Game: Phoenix Suns @ Golden State Warriors
  Line: PHX -1.5
  Prediction: NO BET
  Confidence: 12 (LOW)

  Note: Score differential (3.2) below threshold (5).
  Model doesn't have strong conviction on this game.

How to Interpret Predictions

Factor Breakdown:

Each factor shows the raw value and normalized score (0-100) for both teams. This helps you understand why the model is making a recommendation.

Model Scores:

The weighted sum of all factor scores for each team. The team with the higher score is predicted to cover. The difference determines confidence:

• Difference of 5-15: Low-Medium confidence
• Difference of 15-25: Medium-High confidence
• Difference of 25+: High confidence

NO BET Recommendations:

When the score differential is below your threshold (default: 5), the model outputs "NO BET". This is a feature, not a bug—it prevents you from betting on games with marginal edge.

Taking Action

Based on these predictions, here's a reasonable approach:

1. Denver -6.5 (Confidence: 74) - Strong play. Lakers on B2B, extended road trip, weak defense. Denver well-rested at home.
2. Boston -3.5 (Confidence: 67) - Good play. Celtics' elite defense and rest advantage offset road game.
3. PHX/GSW (Confidence: 12) - Skip. No edge identified.

Step 5: Track Results

After games complete, return to your model to see updated results. The predictions page will show:

• Pending - Game hasn't started
• Win - Your prediction covered
• Loss - Your prediction didn't cover
• Push - Landed exactly on the number

Refining Your Model

After tracking results for a few weeks:

• If high-confidence picks outperform: Consider raising the betting threshold to only bet on 60+ confidence games
• If a factor isn't contributing: Try removing it or reducing its importance
• If you want more bets: Lower the threshold, but expect lower win rate
• To try new factors: Use Preview to test changes before saving

Advanced: Switching to Weighted Mode

Once you've validated your factor selection through backtesting, consider switching to Weighted Mode for precise control:

Based on our backtest, rest factors outperformed.
Adjusted weights:

  team_last_n_pts_allowed_avg: 25%
  rest_days:                   35%  (↑ from 29.4%)
  back_to_back:                20%  (↑ from 17.6%)
  team_ats_record:             15%  (↓ from 17.6%)
  travel_context:              5%   (unchanged)
                              ─────
                              100%

This gives you surgical precision over how the model weighs different inputs, allowing you to fine-tune based on what the backtest data reveals.

Factors System

Factor Categories

Each sport has factors organized into 5 categories, though the specific factors differ based on the sport's characteristics.

Team Performance

Measures how well a team has been playing recently. Examples include scoring averages, points allowed, and home/away performance splits.

Matchup

Analyzes the specific matchup between two teams. Includes head-to-head history and style matchups.

Situational

External factors that affect performance. Rest days, travel distance, back-to-back games, and schedule density all fall into this category.

Player

Accounts for individual player impact. Focuses on star player availability and their effect on team performance.

Score Calculation Methods

Raw factor values are converted to normalized scores (0-100) using one of these methods:

• League Percentile - Score based on ranking vs. all teams in the league (100 = best, 0 = worst)
• Linear Scale - Direct mapping from a defined range to 0-100
• Inverse Linear Scale - For factors where lower is better (e.g., points allowed)
• Boolean Scale - Binary factors converted to advantage/disadvantage scores

Configurable Parameters

Many factors have configurable parameters:

• n_games - Number of recent games to consider (typically 3-30)
• home_only - Only include home games in calculation
• away_only - Only include away games in calculation
• as_favorite / as_underdog - Filter by betting role
• include_playoffs - Include playoff games in history

Factor Summary by Sport

NBA Factors (17)

Team Performance (5)

Matchup (4)

Situational (5)

Player (3)

NFL Factors (18)

Team Performance (6)

Matchup (4)

Situational (4)

Player (4)

NHL Factors (15)

Team Performance (6)

Matchup (3)

Situational (4)

Player (2)

MLB Factors (18)

Team Performance (5)

Matchup (3)

Situational (5)

Player (5)

Building Models

Model Creation Flow

1. Navigate to the Models page
2. Click Create Model
3. Enter a name for your model
4. Select the sport (NBA, NFL, NHL, MLB)
5. Choose the bet type (Spread, Moneyline, Over/Under)
6. Select the mode (Simple or Weighted)
7. Add factors from the available list
8. Assign importance/weights to each factor
9. Run a preview to test performance
10. Save when satisfied

Simple Mode vs Weighted Mode

Simple Mode

Assign importance levels (Low, Medium, High) to each factor. The system converts these to weights using configurable multipliers:

• Low - Default multiplier: 10
• Medium - Default multiplier: 30
• High - Default multiplier: 50

The final weight is calculated as: factor_multiplier / sum_of_all_multipliers

Weighted Mode

Assign precise percentage weights to each factor. Weights must sum to exactly 100%. This mode gives you full control over how much each factor contributes to the final score.

Factor Selection Strategy

Tips for choosing factors:

• Diversify categories - Include factors from multiple categories to capture different aspects
• Consider the bet type - For Over/Under, focus on scoring and pace factors
• Start simple - Begin with 3-5 factors and add more as you understand their impact
• Use backtesting - Test different factor combinations to find what works

Backtesting

What is Backtesting?

Backtesting runs your model against historical games to see how it would have performed. The system calculates factor values using only data available before each game, simulating real-world conditions.

Data Availability

Free Tier Limitations

The free tier limits you to 1 model and 1 week of backtest data. Subscribe to LAB PRO or ALL-ACCESS for unlimited models and full historical access.

Backtest Configuration

• Date range - Start and end dates for the backtest period
• Team filters - Optionally limit to specific teams
• Confidence threshold - Minimum signal strength to place a bet

Understanding Results

• Record - Wins, losses, and pushes
• Win Rate - Percentage of bets won (excluding pushes)
• ROI - Return on investment assuming flat betting
• Results by Confidence - Performance broken down by signal strength

Performance Evaluation

Preview vs Evaluate

What Evaluation Calculates

• Overall record (W/L/P)
• Win rate and ROI
• Average signal strength (confidence)
• Results by confidence bucket (Low/Medium/High)
• Results over time (monthly breakdown)
• Per-game breakdown with predictions

Invalidation

Manual Refresh Required

Backtests and evaluations do not update automatically. When new games are played or odds change, you need to manually re-run the evaluation to include the latest data.

Live Predictions

How Predictions Work

Predictions apply your model's factor weights to upcoming games. For each game, the system:

1. Calculates factor values for both teams
2. Computes weighted scores based on your model configuration
3. Determines the predicted side (home, away, over, under)
4. Assigns a confidence level based on score differential

Prediction Lifecycle

• Pending - Game has not started
• Win - Prediction was correct
• Loss - Prediction was incorrect
• Push - Result matched the line exactly

Manual Refresh Required

• You edit the model
• New games become available
• Opening lines are published

When to Regenerate

Run Generate Predictions:

• After editing model factors or weights
• When the schedule updates (new games added)
• Periodically to capture the latest factor values

Advanced Settings

Importance Multipliers (Simple Mode)

Customize how importance levels translate to weights. Default values:

Adjusting these changes the relative contribution of each importance level. For example, setting High to 100 makes high-importance factors contribute twice as much relative to the default.

Betting Thresholds

Control when to place a bet based on the model's score differential:

Tuning Strategies

• Lower thresholds - More bets, potentially lower edge per bet
• Higher thresholds - Fewer bets, higher conviction required
• Backtest different settings - Use preview to compare threshold configurations

Using with AI Agents

AI Agent Compatibility

The LAB API works great with AI agents like ChatGPT, Claude, and other LLM-powered tools. By providing the OpenAPI specification, AI agents can automatically understand and call the API.

Use Cases

• "Create a model focused on home team performance"
• "Run a backtest for my model and summarize the results"
• "Generate predictions for tonight's games"
• "Compare my models' performance over the last month"
• "Suggest factor combinations for NFL spread betting"

Getting Started with AI Agents

1. Get your API key from the Settings page (requires LAB PRO or ALL-ACCESS)
2. Share the OpenAPI spec URL with your AI agent: https://lab.balldontlie.io/openapi.yaml
3. Describe what you want to do in natural language

Example Prompts

"Using the BDL LAB API, create a new NBA spread model
with factors for scoring average and rest days.
Set scoring average to high importance and rest days
to medium importance."

"Run a backtest on my model 'NFL Sharp' for the
2024 season. Summarize the results including win rate,
ROI, and performance by confidence level."

Tips for AI Agent Usage

• Be specific about sport, bet type, and factors
• Ask for summaries after running operations
• Use the agent to compare multiple configurations
• Have the agent explain factor choices and their impact