Soccer API for Scores, Odds & AI Agents

Available data

Filter with sport=soccer and a league slug when you care about one competition. Discover seasons with GET /v1/seasons?sport=soccer.

Leagues

One page, many slugs. Use league= to narrow; omit it to list across soccer.

/stats is soccer-native across these competitions when aggregates resolve. World Cup TBD placeholders (e.g. “Round of 32 Winner”) return available: false on odds until teams are known.

Schedules

GET /v1/events?sport=soccer — add league=mls (or epl, …). Narrow by status, date or from/to (max 90 days/request), paginate with after_id / limit.

Compound with include_odds=true / include_scores=true for matchday boards in one round trip.

Scores

Soccer period labels: "1H", "2H", "ET1", "ET2", "PKs". Clock examples: "45'+2", "67'".

• GET /v1/events?sport=soccer&status=inprogress&include_scores=true
• GET /v1/events/{id}/score — lightweight poll
• GET /v1/events/{id}/stream — SSE or signed webhooks

Demo: live scoreboard use case.

Odds

Soccer moneyline is 3-way: home, away, and Draw under h2h. Spreads use Asian-style goal lines (e.g. -0.5 / +0.5). Totals are Over/Under. Default Pinnacle = 1 credit; bookmaker=all = 2.

No player props, futures, or alternate lines in v1. History: GET /v1/events/{id}/odds/history. Full books: Sports Odds API.

Stats (Data layer)

GET /v1/events/{id}/stats — soccer-native aggregates: team strength (league table PPG or FIFA rank for WC), recent form, H2H, rest days, home/away splits, boxscore rates, SOS, lineups. No confidence or narrative. Always check available.

Intelligence

Two shapes under one sport — branch correctly:

• MLS — probability model + Price surface (fair / edges_by_book / best vs Pinnacle). Outcomes in a market sum to 1. Price gap ≠ EV.
• FIFA World Cup — points model with confidence, signals._labels (FIFA Ranking Edge, Tournament Context, Travel/Neutral, …), rationale.
• EPL / big-five / UCL — schedules, scores, odds, and /stats today; treat intelligence as available: false until that league’s overlay is live.

Tokens: ML_HOME, ML_AWAY, ML_DRAW, SPREAD_HOME, SPREAD_AWAY, OVER, UNDER.

Sportsbooks

Odds keys: pinnacle, fanduel, draftkings, betmgm, caesars, bet365, circa, hardrock, betonline. Per-event availability varies — especially on EU club fixtures. MLS Price soft set is narrower than the full odds list; always read the payload.

Examples

MLS slate with odds:

curl "https://lumify.ai/v1/events?sport=soccer&league=mls&status=scheduled&include_odds=true&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

from lumify import Lumify

client = Lumify(api_key="YOUR_API_KEY")
page = client.events.list(
    sport="soccer",
    league="mls",
    status="scheduled",
    include_odds=True,
    limit=5,
)
for event in page["events"]:
    print(event["id"], event["name"])

import { Lumify } from "@lumifyai/sdk";

const client = new Lumify({ apiKey: "YOUR_API_KEY" });
const { events } = await client.events.list({
  sport: "soccer",
  league: "mls",
  status: "scheduled",
  includeOdds: true,
  limit: 5,
});
events.forEach(e => console.log(e.id, e.name));

Premier League weekend board:

curl "https://lumify.ai/v1/events?sport=soccer&league=epl&status=scheduled&include_odds=true&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

epl = client.events.list(
    sport="soccer",
    league="epl",
    status="scheduled",
    include_odds=True,
    limit=10,
)

const { events: epl } = await client.events.list({
  sport: "soccer",
  league: "epl",
  status: "scheduled",
  includeOdds: true,
  limit: 10,
});

Sample 3-way moneyline (abridged):

{
  "event_id": 9201,
  "available": true,
  "bookmakers": [
    {
      "bookmaker": "pinnacle",
      "markets": [
        {
          "key": "h2h",
          "label": "moneyline",
          "outcomes": [
            { "outcome": "Inter Miami CF", "price": 145, "point": null },
            { "outcome": "Draw", "price": 240, "point": null },
            { "outcome": "LAFC", "price": 175, "point": null }
          ]
        }
      ],
      "captured_at": "2026-08-10T18:00:00Z"
    }
  ]
}

Freshness

Pricing

Free Tier: 1,000 credits that never expire. Instant trial: 100 credits / 14 days, no signup. Details: /pricing.