EPA Analysis

Default data tool: EndzoneAPI (endzoneapi-tool). get_plays (10 credits) returns plays plus a per-query EPA and success-rate summary. get_team_stats (5 credits) returns season EPA per play and weekly lines. get_player_leaders (5 credits) ranks players on passing_epa, rushing_epa, receiving_epa.

You are an expert in football efficiency metrics. Your goal is to answer "how good is this offense or defense" with a rate, a sample size, and a split that explains it.

When to Use

• "Which offenses were best on third down in 2025?"
• "Is Kansas City's problem passing or running?"
• "How does play action change efficiency?"
• "What is a team's EPA per play when trailing?"
• "Rank quarterbacks by EPA"

When NOT to Use

• Separation, pressure, time to throw, see next-gen-stats
• Win/loss records and schedules, see game-lookup
• FBS or FCS, which do not carry EPA, see college-football
• Turning EPA into a prediction model, see feature-engineering

Commands Available

Commands That Do NOT Exist

Definitions

• EPA (expected points added): points the offense is expected to score on the drive after the play minus before it. A 6 yard gain on 3rd and 10 can be negative.
• EPA per play: mean EPA over a set of plays. The unit is points per play. League-average offense sits near zero by construction; 0.1 per play is a very good offense, -0.1 a bad one.
• Success: a binary per play (success 1 or 0). Success rate is the mean. It ignores play size, so it is steadier than EPA and misses explosive plays.
• WPA: change in win probability from the play. Context-dependent; do not use to rate talent.
• CPOE: completion probability over expected, in percentage points, on pass plays.

Real example from the data: the first 2025 KC third-down pass returned was 3rd and 6, incomplete, epa -1.57, wpa -0.048, success 0. A 40-play pull of that split gave epa_per_play -0.112 and success_rate 0.375. Forty plays is a sample, not a verdict; it shows the shape.

How It Works

Step 1: Choose the scope. Whole-season rate for a team: get_team_stats(team="KC", season=2025). Any split: get_plays with filters.

Step 2: Pull the split with the summary.

get_plays(season=2025, posteam="KC", third_down=true, play_type="pass", limit=1000)

Cost 10. Read data.summary = {plays, epa_total, epa_per_play, success_rate}. The summary covers only the rows returned. Tested live: with limit 1 the summary reported 1 play, with limit 40 it reported 40 (EPA per play -0.112, success rate 0.375 on those first 40 KC third-down passes of 2025). So set limit high enough (up to 1000) to hold the whole split, and check that summary.plays equals the count you expect before quoting a rate. If a split exceeds 1,000 plays, page with offset and next_offset and combine epa_total and plays yourself; never average the per-page rates.

Step 3: Always compute both sides. Offense is posteam. Defense is the same call with defteam. A defense's EPA allowed is the opponent's offensive EPA against it.

Step 4: Split to explain.

Step 5: Exclude the noise. Sacks, penalties and kneels are plays. Decide whether to keep them and say which. Filtering play_type to pass or run mixes in what the source labels as pass plays, which includes sacks; state it. Use the neutral win probability band for any "true talent" claim.

Step 6: Judge the sample. A team plays about 1,000 offensive plays a season. A split with 60 plays has a standard error roughly 0.1 EPA per play wide (play-level EPA standard deviation is near 1.3 to 1.5). Say "n = 60" next to every split. Third-down splits for one season are descriptive, not predictive.

Step 7: Compare to league. One call per team is expensive. For league context use get_player_leaders (5 credits) for player ranks, or compare a team to its own prior weeks via weeks[].

Season Data Check

Real figures from the docs example for 2025 Kansas City (6-11): passing_epa_per_play 0.039, rushing_epa_per_play 0.020, yards_per_attempt 6.76, yards_per_carry 4.21, 3,947 passing yards. The same payload lists passing_epa 24.9 and receiving_epa 109.3 for the team. They are computed on different play sets, so do not expect them to match. Pick one definition and cite it.

Credit Usage

For league-wide work, filter the heavy get_plays pulls to one split and tell the user the cost first.

Anti-patterns

Output Format

KC offense, 2025 regular season
Pass EPA/play 0.039 | Run EPA/play 0.020 (season totals)
3rd down passing: EPA/play X, success X% (n = N plays)
Read: [one sentence, with the weakest split named]
Caveat: [sample, starting QB, garbage time]

What to Do Next

Reference

Python walkthrough: EPA per play: https://endzoneapi.com/guides/nfl-epa-per-play-python