← All guides
On this page
  1. Home
  2. Guides
  3. How do I calculate poker range equity with an API?
Guide Poker semantics · 08/09 Range tools 11 min Intermediate

How do I calculate poker range equity with an API?

Send each player's range, an optional board, and reproducible Monte-Carlo controls to the PokerKit equity endpoint; use the returned shares to explain a supplied scenario, not to predict an outcome.

Updated Maintained by Pokerai API

Direct answer: call POST /v1/pokerkit/equity with ranges containing one notation array per player. Optionally include a board, sample_count, and seed. The response returns one Monte-Carlo equity per supplied range plus the sample count used.

Quick facts

EndpointPOST /v1/pokerkit/equity
InputTwo or more per-player ranges in PokerKit range notation; board is optional.
MethodMonte-Carlo equity estimation. It returns an estimate for the supplied ranges and board, not an odds guarantee.
Responseresult.equities is ordered to match ranges; result.sample_count reports the sampling context.
QuotaThis endpoint charges 1 solve quota. The current Free tier includes 25 real-time solves per month.
AccessPokerKit and GTO endpoints use the same API key. Send one supported API-key header.

Input semantics

Use one nested range array for each player. The array order is significant because returned equities use the same order. A board, when supplied, is an unseparated card string such as AhKhQh.

FieldMeaning
rangesRequired. Per-player arrays of range-notation strings, for example [["AA"], ["KK"]].
boardOptional card string for the known board; omit or use an empty string when no board is known.
sample_countOptional Monte-Carlo sample count. The documented service cap applies; the default is used when it is unset.
seedOptional seed for reproducible sampling.

Minimal API request

This public docs-code example compares AA and KK before the board, with a fixed sample count and seed. Add your API key as the authentication header when making the HTTP request.

{"ranges": [["AA"], ["KK"]], "board": "", "sample_count": 2000, "seed": 7}

Example response and interpretation

{"result": {"equities": [0.8235, 0.1765], "sample_count": 2000}}

The first value, 0.8235, corresponds to the first input range (AA); the second, 0.1765, corresponds to KK. Preserve this ordering in your UI or report.

Read sample_count: 2000 as the number of Monte-Carlo samples used for this response. It describes this estimate's sampling context; it is not a promise about a future deal, a wager, or performance.

When to use this

Use the endpoint in training products, completed-hand review, coaching tools, research, or an explanation UI where the ranges and board are explicit to the user. Store the supplied inputs beside the result so the estimate remains auditable.

When not to use this

Do not use an equity estimate as a real-money, in-hand action prompt; it does not replace player judgment, a complete game model, or a solver strategy. Do not imply that one estimate guarantees a win, a future card, or a betting outcome.

Quota and authentication

Send Authorization: Bearer $POKERAI_API_KEY (or the equivalent X-API-Key) with the request. The endpoint consumes 1 solve quota; the current Free tier has 25 real-time solves per month. Check current usage in the dashboard and read the quotas topic before designing batch work.

Errors

HTTPMeaningWhat to do
401missing_api_key or invalid_api_key.Send one valid API-key header and keep the key out of client logs.
Quotaquota_exceeded when the applicable monthly quota is exhausted.Wait for the monthly reset or adjust the workload; do not retry unchanged requests.
422Request validation failed, such as an invalid body shape.Check the current Reference or OpenAPI schema and correct the input.

Training and review only

Use Pokerai API for training, coaching, hand review, study, and research. Real-time assistance at real-money tables is prohibited. Keep equity displays out of live-table automation and do not turn them into an action recommendation.

Related resources