Endpoints, parameters, fields

Liveness and data readiness of the service, and our clock. Takes no parameters. It does not check your key — the answer is produced before authentication, so a request with no key, or with a key that was never issued, gets the same 200. Use it as a liveness and readiness probe; to verify a key, call GET /v1/usage, which answers 401 on a bad one.

{ "status": "ok", "version": "foreline-gw/1.0", "ts": 1785450885.03,
  "registry": { "readable": true },
  "data": { "warm": true, "events": 684, "files_ingested": 1268,
            "evicted": 0, "last_tick_age_s": 41.2 } }

ts is epoch seconds, not ISO. data is the readiness of the price layer, and it is the field a load balancer should read: on a cold instance it is {"warm": false, "note": …} and the first /v1/surface will be slow while the feed is ingested. status is "ok" with 200, or "degraded" with 500 when the client registry cannot be read — in that state no key authenticates, so it is an outage rather than a per-client problem.

Our event_id, sport, league, both team names, kick-off and the markets we price for each event, plus league_id and sport_id to filter on.

Parameters

Alongside the rows the response carries, at the top level: n (rows returned), n_unnamed, n_without_league_id, sports, sport, hours, live_window_s, league, league_id, note and server_ts. They are top-level keys, not nested under a meta object.

{ "events": [
    { "event_id": 1632737351, "sport": "football",
      "league": "UEFA - Champions League Qualifiers",
      "home": "Shamrock Rovers", "away": "Ararat-Armenia",
      "starts": "2026-07-28T19:00:00Z",
      "markets": ["moneyline", "spread", "totals"], "updated_ts": 1785262578.971,
      "league_id": 2632, "sport_id": 29 }
  ], "n": 1, "n_unnamed": 0, "n_without_league_id": 0, "server_ts": 1785264288.13 }

league_id and sport_id are the last two columns and were added after the first release; they are appended, so the earlier column order is unchanged. league_id may be null on an event whose fixture card predates them — the n_without_league_id counter tells you how many rows in the page that is, and the value fills in once the card is refreshed. In CSV a null is an empty field, as it is for every other column.

The same catalog for events that have already finished — the ids you need to ask /v1/surface?asof= about the past. Give from and to as epoch seconds or ISO-8601 UTC; optional league (exact name) or league_id narrows it. The window may not reach further back than the as-of depth of your plan, otherwise the call returns 403 with your_plan_days. The same from / to switch works on /v1/catalog/leagues, which then counts the historical slice.

Rows carry asof_only: true: for a finished event /v1/surface answers only with ?asof=, and only where the archive covers that moment. markets and updated_ts are omitted — there is no live data behind a finished event.

{ "events": [
    { "event_id": 1632299675, "sport": "football",
      "league": "USA - USL League 2",
      "home": "Motown II", "away": "Long Island Rough Riders",
      "starts": "2026-07-11T00:00:00Z", "asof_only": true,
      "league_id": 214211, "sport_id": 29 }
  ], "mode": "history", "asof_only": true, "your_plan_days": 365, "n": 903 }

History rows carry the same league_id and sport_id, appended after asof_only. Coverage of league_id thins out the further back you go, and it is null where the archived fixture card does not have it; event_id and sport_id are always present.

The same slice reduced to unique leagues, each with an event count, the next kick-off and the league_id to filter on. Same parameters as above, from / to included.

league,sport,events,next_start,league_id
Argentina - Liga Pro,football,4,2026-07-28T22:00:00Z,215171
USA - Major League Soccer,football,15,2026-07-29T00:00:00Z,214211

Rows are still grouped by league name, so the events counts always add up to the event catalog for the same slice. league_id is the id of that league where every event in the row agrees on one; in the rare case where they do not, or where none of the cards carries an id yet, it is null rather than a guess.

No parameters: a summary of what is live right now — the events currently covered, the market keys we hold ticks for, and their freshness. Use it to discover coverage, not to read ladders. It is a full scan, so it sits in the bulk class (4/min) together with the catalog and the delta — not in point. Rows are the events whose last tick is under six hours old, newest first; limit defaults to 500 and is capped at 5000. The envelope is {"events": [...], "data_cadence_s": 30, "data_cadence_tiers_s": {...}}.

{ "events": [
    { "event_id": 1632447496, "sport": "football",
      "league": "Austria - Bundesliga", "starts": "2026-07-31T17:30:00Z",
      "markets": ["away_totals", "home_totals", "moneyline", "spread", "totals"],
      "updated_ts": 1785454018.867, "league_id": 1792, "sport_id": 29 }
  ], "data_cadence_s": 30,
    "data_cadence_tiers_s": { "lt_24h": 30, "24h_96h": 60, "gt_96h": 60 } }

The summary lists every market key we hold a tick for, which is wider than the set we price: home_totals and away_totals appear here and in the line-event feed, but the priced surface itself carries spread, totals and moneyline. There is no n and no server_ts on this response.

Every surface — the summary rows, the single-event object and each event in a ?since= bulk delta — carries the same event descriptor as the catalog: sport, league, home, away, starts, and the league_id / sport_id to filter on. You never have to hold a surface next to a catalog row to know which competition it belongs to.

Parameters

When ?asof= is refused

Four separate rejections, each with its own body — and not one of them costs you an as-of call. The three 400s are refused on the parameters alone; the 403 is refused on your contract. All four return the unit to the asof bucket, so neither a client failing validation nor a backtest walking off the end of your history can exhaust the 20-per-minute allowance on refusals. What every one of them does move is the client-wide rpm / rpd ceiling on your key, which counts requests rather than answers. Clamping the window to your_plan_days on your side is still worth doing — it now protects your key's overall ceiling rather than your asof budget. The whole rule, in one piece, is in Rate limits.

Response — surface object

This is the object returned by ?event_id=, and the same object is what each element of a ?since= delta page contains. Prices live under markets, one entry per market — there is no market, main_line, fair_market or rungs key at the top level.

Bulk-delta envelope: events[], since (echo of what you sent), next_cursor, next_since, more, server_ts, data_cadence_s. Page on next_cursor — see Cursors & paging for why next_since is not the field to loop on.

Response — market fields

Response — rungs[]

curl -s "https://api.foreline.io/v1/surface?event_id=1632432003" \
  -H "X-Foreline-Key: $FORELINE_KEY"

{
  "event_id": 1632432003,
  "sport": "football",
  "league": "England - EFL Cup",
  "starts": "2026-08-01T14:00:00Z",
  "home": "Tranmere Rovers", "away": "Rochdale",
  "league_id": 1982, "sport_id": 29,
  "markets": {
    "spread": {
      "main_line": 0.25, "fair_market": 0.5322,
      "vig": 0.0528, "vig_tier": "high",
      "max_win": 300.0, "limit_tier": "small",
      "updated_ts": 1785455338.5173044,
      "rungs": [
        { "line": -0.75, "p_home": 0.2376, "p_over": null, "src": "table",  "band_pp": [-2.73, 3.13] },
        … seven more rungs …
        { "line": 0.25,  "p_home": 0.5322, "p_over": null, "src": "quote", "band_pp": [0.0, 0.0] }
      ] },
    "totals": {
      "main_line": 2.5, "fair_market": 0.4782,
      "vig": 0.0574, "vig_tier": "high",
      "max_win": 225.0, "limit_tier": "micro",
      "updated_ts": 1785455338.5173044,
      "rungs": [
        { "line": 2.5, "p_home": null, "p_over": 0.4782, "src": "quote", "band_pp": [0.0, 0.0] }
      ] },
    "moneyline": {
      "fair_market": [0.3062, 0.29, 0.4039],
      "fair_calibrated": [0.3062, 0.29, 0.4038],
      "calib_layer": "x12_calib_layer (fit 2024, validated 2026)",
      "tier": "core", "tier_source": "league_id",
      "updated_ts": 1785455338.5173044 } },
  "data_cadence_s": 30,
  "data_cadence_tiers_s": { "lt_24h": 30, "24h_96h": 60, "gt_96h": 60 }
}

Numbers are from one real response and will not match yours. History depth available to ?asof= follows your contract; the archive reaches back to 2022 for football.

Main-line changes as typed facts, in chronological order. This is the catch-up channel: after a restart, replay from your last cursor and you have lost nothing — provided you replay from next_cursor. For live delivery use the stream (push delivery is not available — see Webhooks).

Parameters

Response

curl -s "https://api.foreline.io/v1/line-events?since=0&limit=3" \
  -H "X-Foreline-Key: $FORELINE_KEY"

{ "events": [
    { "ts": 1785432672.737, "event_id": 1632820926,
      "market": "spread", "old_line": -0.25, "new_line": 0.0 }
  ],
  "more": true,
  "next_cursor": "1785432672.7369776:1632820926:1",
  "next_since": 1785432672.7369776,
  "since": "0", "data_cadence_s": 30 }

# next page: the cursor goes back in `since`, unchanged
curl -s "https://api.foreline.io/v1/line-events?since=1785432672.7369776:1632820926:1&limit=3" \
  -H "X-Foreline-Key: $FORELINE_KEY"

A page can come back empty with more: true: the sport filter of your key is applied after the page is assembled, and the cursor still advances past it. Keep going while more is true. Full rules and the measured cost of getting this wrong: Cursors & paging.

A held HTTP connection emitting text/event-stream. Currently one event type, line_change, carrying exactly the row /v1/line-events returns — same field names, same types. The first frame is a comment naming the cadence, then frames as changes are detected, with a : ping comment as keepalive. The connection also has a maximum lifetime, and before closing it emits a : reconnect comment.

Two different stream limits, and they are routinely confused. GET /v1/usage returns both, side by side:

• limits.stream — a [per minute, per day] pair, the rate at which you may open a connection. It is spent by connecting and it refills with time; holding a stream open costs nothing against it.
• stream_concurrent_max — a plain integer, how many streams you may hold open at the same time. It is not a rate and it does not refill: it frees up when one of your streams closes.

They fail differently, which is the practical reason to keep them apart. Exceeding the connect rate is the ordinary 429 quota exceeded carrying class: "stream". Exceeding the concurrent cap is also a 429, but a different one — it names the cap instead of a quota, and waiting for the minute to roll over will not clear it:

# a fourth stream while three are held open, on a key whose cap is 3
→ 429 { "error": "too many concurrent streams", "class": "stream",
        "active_cap": 3, "retry_after": 10 }

Branch on active_cap: its presence means close a stream, not slow down. A worker pool that opens one stream per shard needs stream_concurrent_max shards at most, whatever the connect rate allows — and because a dropped connection frees its slot only once we notice it is gone, a client that reconnects instantly after a network blip can meet this while it still holds the dead slot. Reconnect on the : reconnect comment rather than racing it.

curl -N "https://api.foreline.io/v1/stream" \
  -H "X-Foreline-Key: $FORELINE_KEY"

: foreline sse | data_cadence_s=30

id: 1785432672.7369776
event: line_change
data: {"ts": 1785432672.7369776, "event_id": 1632820926, "market": "spread",
       "old_line": -0.25, "new_line": 0.0}

Resuming. The id: of a frame is its ts, and reconnecting with Last-Event-ID (or ?since=) resumes from that instant. That is a timestamp, not a cursor — rows that share the instant you resume from can arrive twice or not at all. If the gap must be exact, backfill it with /v1/line-events from the last next_cursor you stored, and use the stream for latency rather than for completeness.

Scores an account on closing-line value against our fair close, on the exact lines it took — including lines the reference market never quoted, which are repriced from the ladder tables. Input is an anonymised account identifier and bet parameters; no personal data is accepted or required.

Request body

Response

Reject codes

The full set, every row of it verified against the live API. Branch on code; the note beside it is a sentence for a human and is not an enum. Two of these codes are about the identity of the event and are easy to confuse, so they are written next to each other below — and the right response to one is the exact opposite of the right response to the other.

One rejection is not a row-level code at all: a batch in which any bet is missing event_id is refused whole, with 400, bets_without_event_id (the offending indices), n_bets_without_event_id and a reason. That one is deliberate — matching by team name would silently score the wrong event, so we would rather fail your batch than guess.

Flag thresholds and the flag vocabulary are set per contract during onboarding, so the score can be tuned to your appetite without changing your integration. Bets on events outside your scope are reported as unscored rather than silently dropped.

Gap warnings — where your posted price has drifted from fair — as a journal. It is append-only: every transition of an alert is its own record, so the lifecycle is read by following one key over time rather than by re-reading a mutable object. Page it with since / next_cursor, exactly as the other feeds (Cursors & paging).

Parameters

Response

Envelope: alerts[], since, next_cursor, next_since, more, limit, server_ts. One record looks like this — the names below are the names in the payload:

Comparing your price with fair requires your prices. The optional POST /v1/book-quotes is how they reach us — a batch of your active quotes every 30 seconds, de-vigged and compared rung by rung, with the resulting alerts landing in this same journal and visible only to your key. Nothing is inferred about your book from third-party sources; if you do not send prices, we do not have them. Contract and reject codes: integration guide.

Creates a job and returns 202 immediately. Nothing is computed on this call: rebuilding one as-of surface reads the feed from disk, and an export is hundreds of those, so the work runs on a background worker and the file is fetched separately. Jobs run one at a time, in submission order, across all clients.

curl -X POST "https://api.foreline.io/v1/exports" \
  -H "X-Foreline-Key: $FORELINE_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"surface_asof","format":"csv","event_ids":[1632003658],
       "from":"2026-08-17T00:00:00Z","to":"2026-08-17T05:00:00Z","step_s":3600}'

{ "export_id": "exp_257a206794d114ccd7853b21", "status": "queued", "kind": "surface_asof",
  "format": "csv", "from": "2026-08-17T00:00:00Z", "to": "2026-08-17T05:00:00Z",
  "events": 1, "progress": 0.0, "rows": 0, "bytes": 0,
  "truncated": false, "created": "2026-08-19T01:31:30Z",
  "started": null, "finished": null,
  "expires": "2026-08-21T01:31:30Z",
  "columns": [ "event_id", "asof", "sport", … ], "queue_position": 1 }

Note queue_position: jobs run one at a time across all clients, so a queued job may sit before it starts. from / to and every other timestamp in this response are ISO-8601 with Z, as are the timestamps inside the file itself. When the selector is a league rather than event_ids, events comes back null and an events_note explains that the count is resolved when the job runs.

Your jobs, newest first, plus the current limits object. Only your own jobs are listed — there is no way to see or address another client's export.

Job status. Poll this; a job takes minutes, so once every 10–30 s is plenty.

The file itself: application/gzip with a Content-Disposition filename. Re-downloadable until the job expires. Before the job is done this answers 409 with the current status; after the file is gone, 410. Its own rate class, so a burst of downloads never eats the budget your live surface calls run on.

curl -OJ "https://api.foreline.io/v1/exports/exp_4f1c9a02b7d35e60c8a11d42/download" \
  -H "X-Foreline-Key: $FORELINE_KEY"

Removes the job and its file at once, freeing your export storage, and answers {"export_id": …, "deleted": true}. A job that is still running may be deleted, and deleting it is final: the worker stops, the partial file goes with the job, and from that moment the id answers 404 everywhere — on the status endpoint, on the download endpoint, and by its absence from GET /v1/exports. Fixed: a running job used to come back roughly twenty seconds after it was deleted, when the worker wrote its state back over the deletion, so a client that polled after deleting saw the job return and its storage stay claimed. It no longer returns — checked against the live API by deleting a job mid-run and polling it for two minutes afterwards. An export_id that is not yours — or no longer exists — answers 404 on every one of these endpoints, identically, so the API never confirms that someone else's export exists.

What the product does, before you call it: supported leg types and their aliases, the families we deliberately do not serve and why, the pricing conventions, the measured accuracy and the live ceilings. Read it once at integration time.

Prices one coupon. Send the legs; get back the joint probability, the fair decimal odds, the naive product and the correlation gap, plus a breakdown by leg and by event. Optionally send your own odds and stake and the response also carries the edge and the expected value on that single coupon.

curl -X POST "https://api.foreline.io/v1/parlay/price" \
  -H "X-Foreline-Key: $FORELINE_KEY" -H "Content-Type: application/json" \
  -d '{"legs":[{"event_id":1632003658,"market":"1x2","selection":"home"},
              {"event_id":1632003658,"market":"totals","selection":"over","line":2.75}]}'

{ "priced": true, "n_legs": 2, "n_events": 1,
  "joint_probability": 0.376328, "fair_odds": 2.6573,
  "naive_probability": 0.325497, "naive_odds": 3.0722,
  "correlation_gap_pp": 5.0831, "correlation_gap_pct": 15.62,
  "push_probability": 0.112021,
  "uncertainty_pp": 5.3,
  "uncertainty_basis": "measured calibration maxGap; the wider value applies
                        because this coupon touches the \"home & over\" family",
  "legs": [ { "leg_index": 0, "market": "1x2", "selection": "home", "probability": 0.632412,
               "fair_odds": 1.5812, … },
             { "leg_index": 1, "market": "totals", "selection": "over", "line": 2.75,
               "probability": 0.514692, "push_probability": 0.112021, … } ],
  "events": [ { "event_id": 1632003658, "n_legs": 2, "joint_probability": 0.376328,
               "correlation_gap_pp": 5.0831, "family": "home & over" } ],
  "cross_event": { "n_events": 1, "assumption": "independent" } }

Read that example as the product in one line: a builder multiplying its own marginals would post 3.072 on this coupon. The honest price is 2.657. The 5.08 pp between them is what the multiplication gives away, every time this family is built.

On the uncertainty_pp in that response. It is 5.3, not the 2.1–2.9 headline band, and the uncertainty_basis beside it says why: this coupon is in the home & over family, the one family where our own measurement is worst and which we publish rather than patch — see How accurate this is. A coupon outside that family carries the narrower number. Read uncertainty_pp from the response rather than hard-coding it: it is per-coupon, and it is the number to price against.

A batch of your own coupons, with the prices you actually gave, each priced on the marginals of the moment it was accepted. Per coupon: our joint probability, the probability implied by your price, the edge in points and the expected value in your currency. Plus a summary — which combination families cost you and how much. The report is stored under your account and can be re-read later.

{ "audit_id": "par_4f1c9a02b7d35e60c8a11d42",
  "summary": {
    "tickets": 1, "priced": 1, "unpriced": 0, "currency": "EUR",
    "turnover": 120.0, "expected_value": -23.1841,
    "expected_value_pct_of_turnover": -19.32,
    "money_note": "all money figures are from the operator perspective:
                    positive means you earn, negative means you pay out",
    "leaks": { "tickets": 1, "share_pct": 100.0, "expected_value": -23.1841 },
    "correlation_gap_abs_pp": { "mean": 5.41, "median": 5.41, "p90": 5.41 },
    "by_family": [ { "family": "1x2:home+totals:over", "tickets": 1,
                    "mean_correlation_gap_pp": 5.41, "mean_edge_pp": 6.04,
                    "expected_value": -23.1841 } ],
    "worst_tickets": [ { "ticket_id": "T-1001", "client_odds": 3.2,
                       "fair_odds": 2.6819, "edge_pp": 6.0375 } ] },
  "tickets": [ … one object per coupon, same shape as /v1/parlay/price … ] }

Signs. Money is always from your side of the table: positive means you earn, negative means you pay out. edge_pp is the customer's edge — above zero means your price is generous against our joint probability, and those are the coupons a professional selects. leaks aggregates exactly those.

Your stored reports, newest first, as headers only (id, created, expires, ticket count, turnover, expected value) plus the current limits. Only your own reports are listed.

The full report again, byte for byte as it was computed — the numbers are not recomputed against a newer surface, so a report you show your risk desk next month is the one you were given.

Removes the report. An audit_id that is not yours — or no longer exists — answers 404 on every one of these endpoints, with an identical body, so the API never confirms that someone else's report exists.

Your consumption against the quotas on the key: usage carries the requests you have spent this minute and this day, both against the class of this call and against the key as a whole, and limits carries the [rpm, rpd] pair of every call class on your key. Alongside them it returns stream_concurrent_max — how many SSE streams you may hold open at once, which is a different quantity from the connect rate in limits.stream and is explained by the stream_note in the same response. It needs no scope, only a valid key — which also makes it the honest way to check one. Poll it on a schedule and alert on your own headroom rather than discovering it as 429s.

It also tells you what your plan does not include, before you call it: closed_classes[] lists every call class whose limit is [0, 0] — those calls are rejected with 403, not queued — and exports carries enabled plus, when enabled, the live batch-export ceilings. The same holds for parlay: it says whether joint parlay pricing is on your key and, when it is, carries the supported markets, the ceilings and the measured accuracy — including the family where the model is weakest. Read it once at integration time and you will never discover a missing feature from a production error.

Getting a key (self-serve plans): you buy Starter or Pro in your account (sign-in by email code). After Stripe checkout you are redirected to a one-time page that shows the raw key exactly once — we keep only its sha256. Lost keys are reissued by support. A minimal account page (key → plan, limits, live usage) is at /v1/portal.