Build with the ResultsZA API

Copy-paste scripts for every endpoint, Python and JavaScript.

11 endpoints Python & JavaScript 🟢 Live data previews SA Lotto · Powerball · UK 49s & more

🔑 All examples below use YOUR_API_KEY as a placeholder, replace it with your own key before running. Don't have one? Get an API key →

🎮 Interactive previews, every widget below runs against our live API. Hit ▶ Try live or ↺ Refresh on any card to fetch fresh data. You get 5 refreshes per endpoint for free, or get your own API key for unlimited access.

Get results

Fetch the latest or historic draw results.

Get the latest results for all games

Fetches the most recent draw for every game in a single call. Results are keyed by game name (e.g. lotto_results, powerball_results).

GET/api/get_latest_results

import requests

API_KEY = "YOUR_API_KEY"

resp = requests.get(
    "https://resultsza.co.za/api/get_latest_results",
    params={"api_key": API_KEY},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

# data["results"] keys: lotto_results, powerball_results, daily_lotto_results, etc.
for game_key, r in data.get("results", {}).items():
    nums    = r.get("winning_numbers", [])
    # Each game uses a different field for its special ball
    special = r.get("bonus_ball") or r.get("powerball") or r.get("booster_ball")
    date    = r.get("date", "")[:10]
    draw    = r.get("draw_id")
    label   = r.get("game_type", game_key)
    extra   = f"  +{special}" if special else ""
    print(f"{label:<22}  Draw #{draw:<5}  {date}  {nums}{extra}")

const API_KEY = "YOUR_API_KEY";

const url = new URL("https://resultsza.co.za/api/get_latest_results");
url.searchParams.set("api_key", API_KEY);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

// data.results keys: lotto_results, powerball_results, daily_lotto_results, etc.
for (const [gameKey, r] of Object.entries(data.results ?? {})) {
    // Each game uses a different field for its special ball
    const special = r.bonus_ball ?? r.powerball ?? r.booster_ball ?? null;
    const extra   = special != null ? `  +${special}` : "";
    const date    = (r.date ?? "").slice(0, 10);
    console.log(`${r.game_type ?? gameKey}  Draw #${r.draw_id}  ${date}  ${JSON.stringify(r.winning_numbers)}${extra}`);
}

Live response

Show raw JSON response

{
  "status": "success",
  "results": {
    "powerball_results": {
      "date": "2026-06-12T21:00:00Z",
      "draw_day": "Friday",
      "draw_id": 1728,
      "draw_machine": "KHAYA",
      "game_type": "Powerball",
      "total_pool_size": 13394380.0,
      "total_sales": 26788760.0,
      "winning_numbers": [
        7,
        23,
        27,
        30,
        45
      ],
      "powerball": 6,
      "next_draw_date": null,
      "next_jackpot": 35000000.0,
      "rollover_amount": 22277996.65,
      "rollover_no": 3,
      "divisions": [
        {
          "division": "DIV 1",
          "match": "MATCH 5 + PowerBall",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "DIV 2",
          "match": "MATCH 5",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "DIV 3",
          "match": "MATCH 4 + PowerBall",
          "winners": 18,
          "winning_amount": 39926.9
        },
        {
          "division": "DIV 4",
          "match": "MATCH 4",
          "winners": 272,
          "winning_amount": 2000.0
        },
        {
          "division": "DIV 5",
          "match": "MATCH 3 + PowerBall",
          "winners": 811,
          "winning_amount": 500.0
        },
        {
          "division": "DIV 6",
          "match": "MATCH 3",
          "winners": 12628,
          "winning_amount": 100.0
        },
        {
          "division": "DIV 7",
          "match": "MATCH 2 + PowerBall",
          "winners": 11103,
          "winning_amount": 100.0
        },
        {
          "division": "DIV 8",
          "match": "MATCH 1 + PowerBall",
          "winners": 57173,
          "winning_amount": 20.0
        },
        {
          "division": "DIV 9",
          "match": "MATCH PowerBall",
          "winners": 94294,
          "winning_amount": 10.0
        }
      ]
    },
    "powerball_xtra_results": {
      "date": "2026-06-12T21:00:00Z",
      "draw_day": "Friday",
      "draw_id": 1728,
      "draw_machine": "KHAYA",
      "game_type": "Powerball Xtra",
      "total_pool_size": 5789467.5,
      "total_sales": 11578935.0,
      "winning_numbers": [
        3,
        9,
        32,
        42,
        46
      ],
      "powerball": 1,
      "next_draw_date": null,
      "next_jackpot": 132000000.0,
      "rollover_amount": 119983777.81,
      "rollover_no": 41,
      "divisions": [
        {
          "division": "XTRA DIV 1",
          "match": "MATCH 5 + PowerBall",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "XTRA DIV 2",
          "match": "MATCH 5",
          "winners": 1,
          "winning_amount": 221692.0
        },
        {
          "division": "XTRA DIV 3",
          "match": "MATCH 4 + PowerBall",
          "winners": 17,
          "winning_amount": 6520.3
        },
        {
          "division": "XTRA DIV 4",
          "match": "MATCH 4",
          "winners": 210,
          "winning_amount": 1000.0
        },
        {
          "division": "XTRA DIV 5",
          "match": "MATCH 3 + PowerBall",
          "winners": 550,
          "winning_amount": 250.0
        },
        {
          "division": "XTRA DIV 6",
          "match": "MATCH 3",
          "winners": 9233,
          "winning_amount": 50.0
        },
        {
          "division": "XTRA DIV 7",
          "match": "MATCH 2 + PowerBall",
          "winners": 8725,
          "winning_amount": 50.0
        },
        {
          "division": "XTRA DIV 8",
          "match": "MATCH 1 + PowerBall",
          "winners": 46400,
          "winning_amount": 10.0
        },
        {
          "division": "XTRA DIV 9",
          "match": "MATCH PowerBall",
          "winners": 77040,
          "winning_amount": 5.0
        }
      ]
    },
    "lotto_results": {
      "date": "2026-06-13T21:00:00Z",
      "draw_day": "Saturday",
      "draw_id": 2654,
      "draw_machine": "TSHEGO",
      "game_type": "Lotto",
      "total_pool_size": 5755226.4,
      "total_sales": 11745360.0,
      "winning_numbers": [
        4,
        7,
        19,
        26,
        49,
        50
      ],
      "bonus_ball": 46,
      "next_draw_date": null,
      "next_jackpot": 3000000.0,
      "rollover_amount": 0.0,
      "rollover_no": 0,
      "divisions": [
        {
          "division": "DIV 1",
          "match": "MATCH 6",
          "winners": 1,
          "winning_amount": 23555348.5
        },
        {
          "division": "DIV 2",
          "match": "MATCH 5 + BONUS",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "DIV 3",
          "match": "MATCH 5",
          "winners": 30,
          "winning_amount": 42699.6
        },
        {
          "division": "DIV 4",
          "match": "MATCH 4 + BONUS",
          "winners": 81,
          "winning_amount": 4000.0
        },
        {
          "division": "DIV 5",
          "match": "MATCH 4",
          "winners": 1885,
          "winning_amount": 200.0
        },
        {
          "division": "DIV 6",
          "match": "MATCH 3 + BONUS",
          "winners": 2251,
          "winning_amount": 200.0
        },
        {
          "division": "DIV 7",
          "match": "MATCH 2 + BONUS",
          "winners": 23291,
          "winning_amount": 30.0
        },
        {
          "division": "DIV 8",
          "match": "MATCH 3",
          "winners": 35141,
          "winning_amount": 20.0
        }
      ]
    },
    "lotto_plus1_results": {
      "date": "2026-06-13T21:00:00Z",
      "draw_day": "Saturday",
      "draw_id": 2654,
      "draw_machine": "TSHEGO",
      "game_type": "Lotto Plus 1",
      "total_pool_size": 2458098.47,
      "total_sales": 5016527.5,
      "winning_numbers": [
        6,
        12,
        24,
        32,
        36,
        47
      ],
      "bonus_ball": 49,
      "next_draw_date": null,
      "next_jackpot": 4500000.0,
      "rollover_amount": 2482881.95,
      "rollover_no": 4,
      "divisions": [
        {
          "division": "Plus1 DIV 1",
          "match": "MATCH 6",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "Plus1 DIV 2",
          "match": "MATCH 5 + BONUS",
          "winners": 1,
          "winning_amount": 271795.6
        },
        {
          "division": "Plus1 DIV 3",
          "match": "MATCH 5",
          "winners": 33,
          "winning_amount": 14413.4
        },
        {
          "division": "Plus1 DIV 4",
          "match": "MATCH 4 + BONUS",
          "winners": 81,
          "winning_amount": 2000.0
        },
        {
          "division": "Plus1 DIV 5",
          "match": "MATCH 4",
          "winners": 1663,
          "winning_amount": 100.0
        },
        {
          "division": "Plus1 DIV 6",
          "match": "MATCH 3 + BONUS",
          "winners": 1917,
          "winning_amount": 100.0
        },
        {
          "division": "Plus1 DIV 7",
          "match": "MATCH 2 + BONUS",
          "winners": 19950,
          "winning_amount": 15.0
        },
        {
          "division": "Plus1 DIV 8",
          "match": "MATCH 3",
          "winners": 27987,
          "winning_amount": 10.0
        }
      ]
    },
    "lotto_5_max_results": {
      "date": "2026-06-13T21:00:00Z",
      "draw_day": "Saturday",
      "draw_id": 2654,
      "draw_machine": "TSHEGO",
      "game_type": "Lotto 5 Max",
      "total_pool_size": 2274015.27,
      "total_sales": 4640847.5,
      "winning_numbers": [
        5,
        12,
        19,
        21,
        30,
        46
      ],
      "bonus_ball": 13,
      "next_draw_date": null,
      "next_jackpot": 17000000.0,
      "rollover_amount": 12482350.82,
      "rollover_no": 15,
      "divisions": [
        {
          "division": "5 MAX DIV 1",
          "match": "MATCH 6",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "5 MAX DIV 2",
          "match": "MATCH 5 + BONUS",
          "winners": 1,
          "winning_amount": 237276.0
        },
        {
          "division": "5 MAX DIV 3",
          "match": "MATCH 5",
          "winners": 37,
          "winning_amount": 11222.5
        },
        {
          "division": "5 MAX DIV 4",
          "match": "MATCH 4 + BONUS",
          "winners": 76,
          "winning_amount": 2000.0
        },
        {
          "division": "5 MAX DIV 5",
          "match": "MATCH 4",
          "winners": 1596,
          "winning_amount": 100.0
        },
        {
          "division": "5 MAX DIV 6",
          "match": "MATCH 3 + BONUS",
          "winners": 1982,
          "winning_amount": 100.0
        },
        {
          "division": "5 MAX DIV 7",
          "match": "MATCH 2 + BONUS",
          "winners": 20443,
          "winning_amount": 15.0
        },
        {
          "division": "5 MAX DIV 8",
          "match": "MATCH 3",
          "winners": 27119,
          "winning_amount": 10.0
        }
      ]
    },
    "daily_lotto_results": {
      "date": "2026-06-14T21:00:00Z",
      "draw_day": "Sunday",
      "draw_id": 2647,
      "draw_machine": "RNG1",
      "game_type": "Daily Lotto",
      "total_pool_size": 762625.17,
      "total_sales": 1571451.0,
      "winning_numbers": [
        4,
        18,
        25,
        30,
        36
      ],
      "bonus_ball": null,
      "next_draw_date": null,
      "next_jackpot": 400000.0,
      "rollover_amount": 0.0,
      "rollover_no": 1,
      "divisions": [
        {
          "division": "DIV 1",
          "match": "MATCH 5",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "DIV 2",
          "match": "MATCH 4",
          "winners": 205,
          "winning_amount": 1674.0
        },
        {
          "division": "DIV 3",
          "match": "MATCH 3",
          "winners": 6191,
          "winning_amount": 18.4
        },
        {
          "division": "DIV 4",
          "match": "MATCH 2",
          "winners": 61072,
          "winning_amount": 4.9
        }
      ]
    }
  }
}

Get results for a specific game and date

Returns draw result(s) for the game on the date you specify. Omit date to get the latest draw.

GET/api/get_results_by_game

import requests

API_KEY = "YOUR_API_KEY"
GAME = "Lotto"
DATE = "2026-05-09"

resp = requests.get(
    "https://resultsza.co.za/api/get_results_by_game",
    params={"api_key": API_KEY, "game": GAME, "date": DATE},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

# Each result has draw_id, draw_date, winning_numbers, and bonus_ball / powerball / booster_ball
for r in data.get("results", []):
    nums    = r.get("winning_numbers", [])
    special = r.get("bonus_ball") or r.get("powerball") or r.get("booster_ball")
    date    = r.get("draw_date", "")[:10]
    print(f"Draw #{r.get('draw_id')}  {date}  {r.get('game_name')}")
    print(f"  Numbers : {nums}")
    if special is not None:
        label = "Powerball" if r.get("powerball") else ("Booster" if r.get("booster_ball") else "Bonus")
        print(f"  {label:9}: {special}")

const API_KEY = "YOUR_API_KEY";
const GAME = "Lotto";
const DATE = "2026-05-09";

const url = new URL("https://resultsza.co.za/api/get_results_by_game");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);
url.searchParams.set("date", DATE);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

// Each result has draw_id, draw_date, winning_numbers, bonus_ball / powerball / booster_ball
for (const r of data.results ?? []) {
    const special = r.bonus_ball ?? r.powerball ?? r.booster_ball ?? null;
    const label   = r.powerball != null ? "Powerball" : r.booster_ball != null ? "Booster" : "Bonus";
    console.log(`Draw #${r.draw_id}  ${(r.draw_date ?? "").slice(0, 10)}  ${r.game_name}`);
    console.log(`  Numbers : ${JSON.stringify(r.winning_numbers)}`);
    if (special != null) console.log(`  ${label}: ${special}`);
}

Game Draw date

Live response

Show raw JSON response

{
  "status": "success",
  "results": [
    {
      "game_type": "Lotto",
      "draw_id": "2654",
      "draw_date": "2026-06-13T21:00:00Z",
      "draw_day": "Saturday",
      "draw_machine": "TSHEGO",
      "total_pool_size": 5755226.4,
      "total_sales": 11745360.0,
      "winning_numbers": [
        4,
        7,
        19,
        26,
        49,
        50
      ],
      "bonus_ball": 46,
      "next_draw_date": null,
      "next_jackpot": 3000000.0,
      "rollover_amount": 0.0,
      "rollover_no": 0,
      "divisions": [
        {
          "division": "DIV 1",
          "match": "MATCH 6",
          "winners": 1,
          "winning_amount": 23555348.5
        },
        {
          "division": "DIV 2",
          "match": "MATCH 5 + BONUS",
          "winners": 0,
          "winning_amount": 0.0
        },
        {
          "division": "DIV 3",
          "match": "MATCH 5",
          "winners": 30,
          "winning_amount": 42699.6
        },
        {
          "division": "DIV 4",
          "match": "MATCH 4 + BONUS",
          "winners": 81,
          "winning_amount": 4000.0
        },
        {
          "division": "DIV 5",
          "match": "MATCH 4",
          "winners": 1885,
          "winning_amount": 200.0
        },
        {
          "division": "DIV 6",
          "match": "MATCH 3 + BONUS",
          "winners": 2251,
          "winning_amount": 200.0
        },
        {
          "division": "DIV 7",
          "match": "MATCH 2 + BONUS",
          "winners": 23291,
          "winning_amount": 30.0
        },
        {
          "division": "DIV 8",
          "match": "MATCH 3",
          "winners": 35141,
          "winning_amount": 20.0
        }
      ]
    }
  ]
}

Get UK 49s results

Fetches results for any of the four daily UK 49s draws. Omit date to get the latest draw.

GET/api/get_uk49s_results

import requests

API_KEY = "YOUR_API_KEY"
GAME = "UK49s Teatime"
DATE = "2026-05-09"

resp = requests.get(
    "https://resultsza.co.za/api/get_uk49s_results",
    params={"api_key": API_KEY, "game": GAME, "date": DATE},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

# Each result has draw_date, winning_numbers (6 balls), and booster_ball
for r in data.get("results", []):
    nums    = r.get("winning_numbers", [])
    booster = r.get("booster_ball")
    date    = r.get("draw_date", "")[:10]
    print(f"{GAME}  {date}")
    print(f"  Numbers : {nums}")
    print(f"  Booster : {booster}")

const API_KEY = "YOUR_API_KEY";
const GAME = "UK49s Teatime";
const DATE = "2026-05-09";

const url = new URL("https://resultsza.co.za/api/get_uk49s_results");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);
url.searchParams.set("date", DATE);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

// Each result has draw_date, winning_numbers (6 balls), and booster_ball
for (const r of data.results ?? []) {
    const date = (r.draw_date ?? "").slice(0, 10);
    console.log(`${GAME}  ${date}`);
    console.log("  Numbers :", r.winning_numbers);
    console.log("  Booster :", r.booster_ball);
}

Draw Date

Live response

Show raw JSON response

{
  "status": "success",
  "results": [
    {
      "draw_id": null,
      "game_name": "UK49s Teatime",
      "draw_day": "Sunday",
      "draw_date": "2026-06-14T20:00:00Z",
      "winning_numbers": [
        7,
        8,
        16,
        22,
        26,
        40
      ],
      "booster_ball": 11
    }
  ]
}

Stats & analysis

Hot/cold, frequencies, and pair analysis.

Get hot and cold numbers

Returns the most frequently drawn (hot) and least frequently drawn (cold) numbers for a game.

GET/api/get_hot_cold_numbers_stats

import requests, random

API_KEY = "YOUR_API_KEY"
PRODUCT = "Lotto"

resp = requests.get(
    "https://resultsza.co.za/api/get_hot_cold_numbers_stats",
    params={"api_key": API_KEY, "product": PRODUCT},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

hot  = data.get("hot",  [])
cold = data.get("cold", [])

print(f"🔥 Hottest {PRODUCT} numbers : {hot}")
print(f"❄️  Coldest {PRODUCT} numbers : {cold}")

# Build a blended pick — 4 hot numbers + 2 cold numbers
pick = sorted(random.sample(hot[:10], 4) + random.sample(cold[:10], 2))
print(f"
Blended lucky pick: {pick}")

const API_KEY = "YOUR_API_KEY";
const PRODUCT = "Lotto";

const url = new URL("https://resultsza.co.za/api/get_hot_cold_numbers_stats");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("product", PRODUCT);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

const hot  = data.hot  ?? [];
const cold = data.cold ?? [];

console.log(`🔥 Hottest ${PRODUCT} numbers:`, hot);
console.log(`❄️  Coldest ${PRODUCT} numbers:`, cold);

// Build a blended pick — 4 hot + 2 cold
const sample = (arr, n) => [...arr].sort(() => Math.random() - 0.5).slice(0, n);
const pick = [...sample(hot.slice(0, 10), 4), ...sample(cold.slice(0, 10), 2)].sort((a, b) => a - b);
console.log("Blended lucky pick:", pick);

Game

Live response

Show raw JSON response

{
  "cold": [
    36,
    21,
    37,
    50,
    51,
    52
  ],
  "hot": [
    8,
    16,
    48,
    23,
    14,
    30
  ],
  "product": "Lotto",
  "status": "success"
}

Get number draw frequencies

Returns how many times each number has been drawn, plus the date it was last drawn.

GET/api/get_number_frequencies

import requests

API_KEY = "YOUR_API_KEY"
PRODUCT = "Lotto"

resp = requests.get(
    "https://resultsza.co.za/api/get_number_frequencies",
    params={"api_key": API_KEY, "product": PRODUCT},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

stats   = data.get("statistics", [])
top10   = stats[:10]
max_frq = top10[0]["frequency"] if top10 else 1

print(f"Top 10 most-drawn {PRODUCT} numbers:
")
for s in top10:
    bar = "█" * round(s["frequency"] / max_frq * 20)
    print(f"  {s['number']:>3}  {bar:<21}  {s['frequency']}x   last: {s['last_drawn']}")

const API_KEY = "YOUR_API_KEY";
const PRODUCT = "Lotto";

const url = new URL("https://resultsza.co.za/api/get_number_frequencies");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("product", PRODUCT);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

const top10   = (data.statistics ?? []).slice(0, 10);
const maxFreq = top10[0]?.frequency ?? 1;

console.log(`Top 10 most-drawn ${PRODUCT} numbers:
`);
for (const s of top10) {
    const bar = "█".repeat(Math.round(s.frequency / maxFreq * 20));
    console.log(`  ${String(s.number).padStart(3)}  ${bar.padEnd(21)}  ${s.frequency}x   last: ${s.last_drawn}`);
}

Game

Live response

Show raw JSON response

{
  "product": "Lotto",
  "statistics": [
    {
      "frequency": 2,
      "last_drawn": "2026-06-06",
      "number": 8
    },
    {
      "frequency": 2,
      "last_drawn": "2026-06-10",
      "number": 16
    },
    {
      "frequency": 2,
      "last_drawn": "2026-06-13",
      "number": 19
    },
    {
      "frequency": 2,
      "last_drawn": "2026-06-13",
      "number": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number": 4
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number": 5
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number": 7
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number": 15
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number": 17
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number": 18
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number": 20
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number": 25
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number": 26
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number": 30
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number": 40
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number": 44
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number": 46
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number": 49
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number": 51
    }
  ],
  "status": "success"
}

Get most common number pairs

Returns pairs of numbers that have appeared together most often in the same draw.

GET/api/get_number_pairs

import requests

API_KEY = "YOUR_API_KEY"
PRODUCT = "Lotto"

resp = requests.get(
    "https://resultsza.co.za/api/get_number_pairs",
    params={"api_key": API_KEY, "product": PRODUCT},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

pairs = data.get("pairs", [])
print(f"Most common {PRODUCT} number pairs:
")
for p in pairs[:10]:
    print(f"  [{p['number1']:>3}] + [{p['number2']:>3}]  —  together {p['frequency']}x   last: {p['last_drawn']}")

const API_KEY = "YOUR_API_KEY";
const PRODUCT = "Lotto";

const url = new URL("https://resultsza.co.za/api/get_number_pairs");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("product", PRODUCT);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

console.log(`Most common ${PRODUCT} number pairs:
`);
for (const p of (data.pairs ?? []).slice(0, 10)) {
    console.log(`  [${String(p.number1).padStart(3)}] + [${String(p.number2).padStart(3)}]  —  together ${p.frequency}x   last: ${p.last_drawn}`);
}

Game

Live response

Show raw JSON response

{
  "pairs": [
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 4,
      "number2": 19
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 4,
      "number2": 26
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 19,
      "number2": 26
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 7,
      "number2": 49
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 26,
      "number2": 49
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 7,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 26,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 4,
      "number2": 7
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 7,
      "number2": 19
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 7,
      "number2": 26
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 4,
      "number2": 49
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 19,
      "number2": 49
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 4,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 19,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-13",
      "number1": 49,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 15,
      "number2": 16
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 16,
      "number2": 17
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 16,
      "number2": 18
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 15,
      "number2": 25
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 17,
      "number2": 25
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 15,
      "number2": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 17,
      "number2": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 25,
      "number2": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 15,
      "number2": 17
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 15,
      "number2": 18
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 17,
      "number2": 18
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 16,
      "number2": 25
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 18,
      "number2": 25
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 16,
      "number2": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-10",
      "number1": 18,
      "number2": 33
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 8,
      "number2": 16
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 16,
      "number2": 20
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 16,
      "number2": 40
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 8,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 20,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 8,
      "number2": 51
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 20,
      "number2": 51
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 50,
      "number2": 51
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 8,
      "number2": 20
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 8,
      "number2": 40
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 20,
      "number2": 40
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 16,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 40,
      "number2": 50
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 16,
      "number2": 51
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-06",
      "number1": 40,
      "number2": 51
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 5,
      "number2": 8
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 8,
      "number2": 19
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 8,
      "number2": 30
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 5,
      "number2": 44
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 19,
      "number2": 44
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 5,
      "number2": 46
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 19,
      "number2": 46
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 44,
      "number2": 46
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 5,
      "number2": 19
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 5,
      "number2": 30
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 19,
      "number2": 30
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 8,
      "number2": 44
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 30,
      "number2": 44
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 8,
      "number2": 46
    },
    {
      "frequency": 1,
      "last_drawn": "2026-06-03",
      "number1": 30,
      "number2": 46
    }
  ],
  "product": "Lotto",
  "status": "success"
}

Generate numbers

Random or text-derived lucky numbers.

Generate random numbers

Generates one or more sets of random numbers that are valid for the chosen game.

GET/api/generate_random_numbers

import requests

API_KEY = "YOUR_API_KEY"
GAME  = "Lotto"
LINES = 5

resp = requests.get(
    "https://resultsza.co.za/api/generate_random_numbers",
    params={"api_key": API_KEY, "game": GAME, "lines": LINES},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

print(f"Generated {data.get('lines')} lucky lines for {data.get('game')}:
")
for i, line in enumerate(data.get("random_numbers", []), start=1):
    # Powerball returns {"main_numbers": [...], "powerball": N}; other games return a plain list
    if isinstance(line, dict):
        nums = line.get("main_numbers", [])
        pb   = line.get("powerball")
        print(f"  Line {i}: {nums}  PB: {pb}")
    else:
        print(f"  Line {i}: {line}")

const API_KEY = "YOUR_API_KEY";
const GAME  = "Lotto";
const LINES = 5;

const url = new URL("https://resultsza.co.za/api/generate_random_numbers");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);
url.searchParams.set("lines", LINES);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

console.log(`Generated ${data.lines} lucky lines for ${data.game}:
`);
data.random_numbers?.forEach((line, i) => {
    // Powerball returns {main_numbers, powerball}; other games return a plain array
    if (Array.isArray(line)) {
        console.log(`  Line ${i + 1}:`, line);
    } else {
        console.log(`  Line ${i + 1}:`, line.main_numbers, `  PB: ${line.powerball}`);
    }
});

Game Lines

Live response

Show raw JSON response

{
  "game": "Lotto",
  "lines": 1,
  "random_numbers": [
    [
      14,
      17,
      18,
      26,
      28,
      44
    ]
  ],
  "status": "success"
}

Convert text into lucky numbers

Hashes any text (a name, a phrase, a birthday) into a set of game-valid numbers.

POST/api/text_to_lucky_numbers

import requests

API_KEY = "YOUR_API_KEY"
GAME = "Lotto"
TEXT = "happy birthday Grandma"

resp = requests.post(
    "https://resultsza.co.za/api/text_to_lucky_numbers",
    params={"api_key": API_KEY, "game": GAME},
    json={"text": TEXT},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

print(f"Text   : {data.get('text')}")
print(f"Game   : {data.get('game_type')}")
print(f"Numbers: {data.get('lucky_numbers')}")
if data.get("powerball") is not None:
    print(f"PB     : {data.get('powerball')}")

const API_KEY = "YOUR_API_KEY";
const GAME = "Lotto";
const TEXT = "happy birthday Grandma";

const url = new URL("https://resultsza.co.za/api/text_to_lucky_numbers");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);

const resp = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: TEXT }),
    signal: AbortSignal.timeout(10000),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

console.log("Text   :", data.text);
console.log("Game   :", data.game_type);
console.log("Numbers:", data.lucky_numbers);
if (data.powerball != null) console.log("PB     :", data.powerball);

Game Your text

Live response

Show raw JSON response

{
  "game_type": "Lotto",
  "lucky_numbers": [
    43,
    35,
    39,
    37,
    14,
    22
  ],
  "status": "success",
  "text": "ResultsZA"
}

Check your numbers

See if your numbers won — single, bulk, or stored.

Check if your numbers won

Checks up to 10 lines of numbers against the draw results for a given game and date.

POST/api/check_played_numbers

import requests

API_KEY = "YOUR_API_KEY"
GAME = "Lotto"
DATE = "2026-05-09"

resp = requests.post(
    "https://resultsza.co.za/api/check_played_numbers",
    params={"api_key": API_KEY, "game": GAME, "date": DATE},
    json={"played_numbers": [7, 14, 21, 28, 35, 42]},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

r       = data.get("results", {})
outcome = r.get("result", {})
matches = outcome.get("matches", {})
special = r.get("bonus_ball") or r.get("powerball")

print(f"Draw : {data.get('draw_date')}  ({data.get('game')})")
print(f"Drawn: {r.get('winning_numbers')}" + (f"  +{special}" if special else ""))
print(f"Yours: {r.get('played_numbers')}")
print(f"Main matches : {matches.get('main_matches', 0)}")

if outcome.get("division"):
    print(f"🏆 Division {outcome['division']} winner!  Prize: R{outcome.get('winning_amount')}")
else:
    print("No division win this draw.")

const API_KEY = "YOUR_API_KEY";
const GAME = "Lotto";
const DATE = "2026-05-09";

const url = new URL("https://resultsza.co.za/api/check_played_numbers");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);
url.searchParams.set("date", DATE);

const resp = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ played_numbers: [7, 14, 21, 28, 35, 42] }),
    signal: AbortSignal.timeout(10000),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

const r       = data.results ?? {};
const outcome = r.result ?? {};
const matches = outcome.matches ?? {};
const special = r.bonus_ball ?? r.powerball ?? null;

console.log(`Draw : ${data.draw_date}  (${data.game})`);
console.log(`Drawn: ${JSON.stringify(r.winning_numbers)}` + (special != null ? `  +${special}` : ""));
console.log(`Yours: ${JSON.stringify(r.played_numbers)}`);
console.log(`Main matches : ${matches.main_matches ?? 0}`);

if (outcome.division) {
    console.log(`🏆 Division ${outcome.division} winner!  Prize: R${outcome.winning_amount}`);
} else {
    console.log("No division win this draw.");
}

ℹ️ Lotto/Daily Lotto: enter main numbers only. Powerball/Powerball Plus: enter 5 main numbers then the Powerball as the last number (e.g. 1, 2, 3, 4, 5, 7 — where 7 is the Powerball).

Game Draw date Your numbers

Live response

Show raw JSON response

{
  "status": "success",
  "game": "Lotto",
  "draw_date": "2026-01-21",
  "results": {
    "played_numbers": [
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "winning_numbers": [
      9,
      18,
      32,
      35,
      54,
      56
    ],
    "bonus_ball": 2,
    "result": {
      "matches": {
        "main_matches": 0,
        "bonus_match": true
      },
      "division": null,
      "winning_amount": null
    }
  }
}

Bulk-check up to 500 lines

Checks up to 500 lines of numbers against a single draw — ideal for checking a full season of tickets.

POST/api/bulk_check_numbers

import requests

API_KEY = "YOUR_API_KEY"
GAME = "Lotto"
DATE = "2026-05-09"

tickets = [
    [1,  2,  3,  4,  5,  6],
    [7,  14, 21, 28, 35, 42],
    [10, 20, 30, 40, 50, 58],
]

resp = requests.post(
    "https://resultsza.co.za/api/bulk_check_numbers",
    params={"api_key": API_KEY, "game": GAME, "date": DATE},
    json={"played_numbers": tickets},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

winners = sum(1 for r in data.get("results", {}).values() if r.get("result", {}).get("division"))
print(f"Checked {data.get('lines_checked')} tickets for {data.get('game')} on {data.get('draw_date')}")
print(f"Winners: {winners}
")

for key, r in data.get("results", {}).items():
    nums    = r.get("played_numbers", [])
    m       = r.get("result", {}).get("matches", {}).get("main_matches", 0)
    div     = r.get("result", {}).get("division")
    amount  = r.get("result", {}).get("winning_amount")
    status  = f"🏆 Div {div} — R{amount}" if div else f"No win ({m} match{'es' if m != 1 else ''})"
    print(f"  {key}: {nums}  →  {status}")

const API_KEY = "YOUR_API_KEY";
const GAME = "Lotto";
const DATE = "2026-05-09";

const tickets = [
    [1,  2,  3,  4,  5,  6],
    [7,  14, 21, 28, 35, 42],
    [10, 20, 30, 40, 50, 58],
];

const url = new URL("https://resultsza.co.za/api/bulk_check_numbers");
url.searchParams.set("api_key", API_KEY);
url.searchParams.set("game", GAME);
url.searchParams.set("date", DATE);

const resp = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ played_numbers: tickets }),
    signal: AbortSignal.timeout(10000),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

const results = data.results ?? {};
const winners = Object.values(results).filter(r => r.result?.division).length;
console.log(`Checked ${data.lines_checked} tickets for ${data.game} on ${data.draw_date}`);
console.log(`Winners: ${winners}
`);

for (const [key, r] of Object.entries(results)) {
    const m      = r.result?.matches?.main_matches ?? 0;
    const div    = r.result?.division;
    const amount = r.result?.winning_amount;
    const status = div ? `🏆 Div ${div} — R${amount}` : `No win (${m} match${m !== 1 ? "es" : ""})`;
    console.log(`  ${key}: ${JSON.stringify(r.played_numbers)}  →  ${status}`);
}

ℹ️ One ticket per line. Lotto/Daily Lotto: main numbers only. Powerball: 5 main numbers then the Powerball as the last number on each line (e.g. 1, 2, 3, 4, 5, 7 — where 7 is the Powerball).

Game Draw date Tickets (one per line)

Live response

Numbers	Matches	Result	Won
123456	0	No win
789101112	1	No win

Show raw JSON response

{
  "status": "success",
  "game": "Lotto",
  "draw_date": "2026-01-21",
  "lines_checked": 2,
  "results": {
    "line1_results": {
      "played_numbers": [
        1,
        2,
        3,
        4,
        5,
        6
      ],
      "winning_numbers": [
        9,
        18,
        32,
        35,
        54,
        56
      ],
      "bonus_ball": 2,
      "result": {
        "matches": {
          "main_matches": 0,
          "bonus_match": true
        },
        "division": null,
        "winning_amount": null
      }
    },
    "line2_results": {
      "played_numbers": [
        7,
        8,
        9,
        10,
        11,
        12
      ],
      "winning_numbers": [
        9,
        18,
        32,
        35,
        54,
        56
      ],
      "bonus_ball": 2,
      "result": {
        "matches": {
          "main_matches": 1,
          "bonus_match": false
        },
        "division": null,
        "winning_amount": null
      }
    }
  }
}

Account

Check your monthly quota.

Check your API key balance

Returns remaining tokens or subscription usage details for your API key.

GET/check_api_key_balance

import requests

API_KEY = "YOUR_API_KEY"

resp = requests.get(
    "https://resultsza.co.za/check_api_key_balance",
    params={"api_key": API_KEY},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

billing = data.get("billing_model")
print(f"Billing model : {billing}")

if billing == "token":
    print(f"Tokens left   : {data.get('tokens_remaining')}")
else:
    tier      = data.get("tier")
    status    = data.get("subscription_status")
    remaining = data.get("remaining")
    unlimited = data.get("is_unlimited", False)
    print(f"Tier          : {tier}  ({status})")
    print(f"Calls left    : {'Unlimited' if unlimited else remaining}")

const API_KEY = "YOUR_API_KEY";

const url = new URL("https://resultsza.co.za/check_api_key_balance");
url.searchParams.set("api_key", API_KEY);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();

console.log("Billing model :", data.billing_model);

if (data.billing_model === "token") {
    console.log("Tokens left   :", data.tokens_remaining);
} else {
    console.log(`Tier          : ${data.tier}  (${data.subscription_status})`);
    console.log(`Calls left    : ${data.is_unlimited ? "Unlimited" : data.remaining}`);
}

ℹ️ Paste a real API key — this calls the live balance endpoint (free, no quota deducted).

API key

💡 Best-practice patterns

Avoid common mistakes. Save quota.

Respect rate-limit headers (Unlimited tier only)

Read X-RateLimit-Remaining on every response. Pause before you hit zero, or you'll trigger a 5-minute cooldown.

import time
import requests

API_KEY = "YOUR_API_KEY"
MAX_RETRIES = 5  # bail out after this many cooldown bounces


def call_with_backoff(url, params):
    for attempt in range(MAX_RETRIES):
        resp = requests.get(url, params=params, timeout=10)

        # Pre-empt the cooldown: if the window is nearly full, sleep until reset
        remaining = int(resp.headers.get("X-RateLimit-Remaining", "60"))
        if remaining < 5:
            reset_ts = int(resp.headers.get("X-RateLimit-Reset", time.time() + 60))
            time.sleep(max(0, reset_ts - time.time()))

        if resp.status_code != 429:
            resp.raise_for_status()
            return resp.json()

        # Rate-limited: sleep the cooldown and retry
        cooldown = int(resp.headers.get("X-RateLimit-Cooldown", "300"))
        print(f"Cooldown active ({cooldown}s). Attempt {attempt + 1} of {MAX_RETRIES}.")
        time.sleep(cooldown)

    raise RuntimeError(f"Still rate-limited after {MAX_RETRIES} attempts; giving up.")


for game in ["Lotto", "Lotto Plus 1", "Lotto 5 Max"]:
    print(call_with_backoff(
        "https://resultsza.co.za/api/get_latest_results",
        {"api_key": API_KEY, "game": game},
    ))

const API_KEY = "YOUR_API_KEY";
const MAX_RETRIES = 5;

async function callWithBackoff(url, params) {
    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
        const u = new URL(url);
        Object.entries(params).forEach(([k, v]) => u.searchParams.set(k, v));
        const resp = await fetch(u, { signal: AbortSignal.timeout(10000) });

        // Pre-empt the cooldown: if the window is nearly full, sleep until reset
        const remaining = parseInt(resp.headers.get("X-RateLimit-Remaining") || "60", 10);
        if (remaining < 5) {
            const resetTs = parseInt(resp.headers.get("X-RateLimit-Reset") || "0", 10);
            const waitMs = Math.max(0, resetTs * 1000 - Date.now());
            await new Promise(r => setTimeout(r, waitMs));
        }

        if (resp.status !== 429) {
            if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
            return resp.json();
        }

        // Rate-limited: sleep the cooldown and retry
        const cooldown = parseInt(resp.headers.get("X-RateLimit-Cooldown") || "300", 10);
        console.log(`Cooldown active (${cooldown}s). Attempt ${attempt + 1} of ${MAX_RETRIES}.`);
        await new Promise(r => setTimeout(r, cooldown * 1000));
    }

    throw new Error(`Still rate-limited after ${MAX_RETRIES} attempts; giving up.`);
}

for (const game of ["Lotto", "Lotto Plus 1", "Lotto 5 Max"]) {
    console.log(await callWithBackoff(
        "https://resultsza.co.za/api/get_latest_results",
        { api_key: API_KEY, game },
    ));
}

Check your monthly quota before bulk operations

Avoid mid-job failures: hit /check_api_key_balance first and bail out early if you don't have enough credit.

import requests

API_KEY = "YOUR_API_KEY"
NEEDED_CALLS = 500

resp = requests.get(
    "https://resultsza.co.za/check_api_key_balance",
    params={"api_key": API_KEY},
    timeout=10,
)
resp.raise_for_status()
balance = resp.json()

billing_model = balance.get("billing_model")

if billing_model == "subscription":
    remaining = balance.get("remaining")
    if remaining == "Unlimited (Fair Use)" or balance.get("is_unlimited"):
        print("Unlimited tier — proceed.")
    elif isinstance(remaining, int) and remaining < NEEDED_CALLS:
        raise SystemExit(f"Only {remaining} calls left this month, need {NEEDED_CALLS}. Aborting.")
    else:
        print(f"OK — {remaining} calls available, will use {NEEDED_CALLS}.")
        # ... your bulk job here
elif billing_model == "token":
    # Token plan: server returns tokens_remaining instead
    tokens = balance.get("tokens_remaining", 0)
    if tokens < NEEDED_CALLS:
        raise SystemExit(f"Only {tokens} token calls left, need {NEEDED_CALLS}. Aborting.")
    print(f"OK — {tokens} token calls available.")
else:
    raise SystemExit(f"Unrecognised billing_model: {billing_model!r}")

const API_KEY = "YOUR_API_KEY";
const NEEDED_CALLS = 500;

const url = new URL("https://resultsza.co.za/check_api_key_balance");
url.searchParams.set("api_key", API_KEY);

const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const balance = await resp.json();

const billingModel = balance.billing_model;

if (billingModel === "subscription") {
    const remaining = balance.remaining;
    if (balance.is_unlimited || remaining === "Unlimited (Fair Use)") {
        console.log("Unlimited tier — proceed.");
    } else if (typeof remaining === "number" && remaining < NEEDED_CALLS) {
        throw new Error(`Only ${remaining} calls left this month, need ${NEEDED_CALLS}. Aborting.`);
    } else {
        console.log(`OK — ${remaining} calls available, will use ${NEEDED_CALLS}.`);
        // ... your bulk job here
    }
} else if (billingModel === "token") {
    // Token plan: server returns tokens_remaining instead
    const tokens = balance.tokens_remaining || 0;
    if (tokens < NEEDED_CALLS) {
        throw new Error(`Only ${tokens} token calls left, need ${NEEDED_CALLS}. Aborting.`);
    }
    console.log(`OK — ${tokens} token calls available.`);
} else {
    throw new Error(`Unrecognised billing_model: ${billingModel}`);
}