Using LineupAPI
Tutorial: Using LineupAPI
This tutorial walks you through the most common workflow:
- Get a
fixtureIdfrom /fixtures - Request predictions for that fixture (choose groups)
- Read credit usage from response headers
- (Optional) Request a historical prediction via /history/
How fresh is the data?
LineupAPI predictions are published as snapshots.
- A new fixtures snapshot is created every 15 minutes
- Fixtures are available up to 17 days in advance (forecast window)
- Predictions refresh once per day per fixture (not every 15 minutes)
- The refresh happens exactly 24 hours before the fixture’s planned kickoff time (within the 17-day horizon)
lineupsforecast uses the most up-to-date player availability signals available at the time of the refresh
Tip
If you want to minimize calls, fetch predictions once per day after the scheduled refresh. Fixtures can be checked more often (every 15 minutes) to discover newly added games or changes in the upcoming schedule.
Host
All requests use the host https://api.lineupapi.com/v2/
Example: https://api.lineupapi.com/v2/fixtures?apiKey={apiKey}
Step 1 — Call /fixtures to get a fixtureId
Important
Replace YOUR_API_KEY with your real key from the dashboard.
URL
GET https://api.lineupapi.com/v2/fixtures/?apiKey={apiKey}
Example
URL https://api.lineupapi.com/v2/fixtures/?apiKey=YOUR_API_KEY
Try it in the browser
What to look for
In the response, find a fixtureId in UUID format, e.g. f61793bf-59e8-4d1b-81bd-458a1fd138dd
You will reuse this ID for /predictions/{fixtureId} and history endpoints.
Step 2 — Call /predictions/{fixtureId} with groups
URL
GET https://api.lineupapi.com/v2/predictions/{fixtureId}/?apiKey={apiKey}&groups={groups}
Available groups
lineups— starter / benchAndPlay / notPlay probabilities (%)minutes— minutes-played bucket probabilities (%)goals— goal threshold probabilities (%)assists— assist threshold probabilities (%)cards— yellow / red / no card probabilities (%)corners_taken— corners taken threshold probabilities (%)fouls_won— fouls won threshold probabilities (%)fouls_conceded— fouls conceded threshold probabilities (%)
If you include all as any group value, the API returns all available groups.
Example (recommended: start small)
URLhttps://api.lineupapi.com/v2/predictions/f61793bf-59e8-4d1b-81bd-458a1fd138dd/?groups=lineups&apiKey=YOUR_API_KEY
Try it in the browser
Example (all groups)
URLhttps://api.lineupapi.com/v2/predictions/f61793bf-59e8-4d1b-81bd-458a1fd138dd/?groups=all&apiKey=YOUR_API_KEY
Try it in the browser
Step 3 (optional) — Check credit headers
Advanced developers: Credit information is also returned as HTTP response headers.
If you’re calling the API from browser, code, a REST client, or curl, you can read these headers:
- x-credits-cost: credit cost of this request
- x-credits-used: credits used since last reset
- x-credits-remaining: credits remaining until next reset
If a request fails (non-2xx response code), it does not consume credits.
Prediction cost rule
For /predictions, the request cost scales with the number of unique groups requested:
cost = 1 x [number of unique groups]
So:
groups=lineups→ cost 1groups=lineups,minutes,goals→ cost 3groups=all→ cost depends on all available groups
Tip
Ask only for the groups you actually need to minimize cost.
Step 4 (optional) — Explore snapshot timestamps & models
The predictions you receive are generated in snapshots (think: “saved versions” of the prediction at different points in time).
The metadata endpoint lets you inspect:
- the latest snapshot timestamp
- all previous snapshot timestamps (useful for
/historyURLs) - each snapshot’s creation time
- the model/version (and related identifiers) that produced it
URL
GET https://api.lineupapi.com/v2/predictions/metadata/{fixtureId}/?apiKey={apiKey}
Example
URLhttps://api.lineupapi.com/v2/predictions/metadata/f61793bf-59e8-4d1b-81bd-458a1fd138dd/?apiKey=YOUR_API_KEY
Try it in the browser
Tip
Use any returned snapshot timestamp as the date parameter for History:
/v2/history/predictions/{fixtureId}/?date={snapshotTimestamp}&apiKey={apiKey}
That returns predictions exactly as they looked at that snapshot.
Step 5 (optional) — Historical predictions
History endpoints gives you fixtures and predictions "as they looked at a past snapshot time".
5A — Find fixtures for a historical snapshot
GET https://api.lineupapi.com/v2/history/fixtures/?date={date}&apiKey={apiKey}
Example: https://api.lineupapi.com/v2/history/fixtures/?date=2025-04-24T16:00:00Z&apiKey=YOUR_API_KEY
Try it in the browser
https://api.lineupapi.com/v2/history/fixtures/?date=2025-04-24T16:00:00Z&apiKey=YOUR_API_KEY
Note
- The API returns the closest snapshot at or before the timestamp you provide.
- Advanced developers can find these timestamp headers in the response:
- x-timestamp-requested: the
datevalue you requested (ISO 8601) - x-timestamp-current: the snapshot timestamp actually returned (ISO 8601)
- x-timestamp-previous: the closest snapshot timestamp before
x-timestamp-current(if available) - x-timestamp-next: the closest snapshot timestamp after
x-timestamp-current(if available)
- x-timestamp-requested: the
Tips
These headers make it easy to page backward/forward through time without guessing the next valid snapshot timestamp.
5B — Fetch historical predictions for a fixture
GET https://api.lineupapi.com/v2/history/predictions/{fixtureId}/?apiKey={apiKey}&groups={groups}&date={date}
Example: https://api.lineupapi.com/v2/history/predictions/f61793bf-59e8-4d1b-81bd-458a1fd138dd/?groups=lineups,minutes&date=2025-04-24T16:00:00Z&apiKey=YOUR_API_KEY
Try it in the browser
Common HTTP errors
- 401 Unauthorized — Invalid or inactive
apiKey. - 402 Payment Required — Insufficient credits (you reached your quota cap).
- 404 Not Found — Wrong path, resource not found, or unknown
fixtureId. - 429 Too Many Requests — Rate limit exceeded. Slow down, or retry with exponential backoff.
See the full list here: /learn/errors-and-status-codes