← All guides
On this page
  1. Home
  2. Guides
  3. How do I get preflop strategy from an API?
Guide GTO strategy · 06/06 Range tools 12 min Beginner

How do I get preflop strategy from an API?

Call POST /v1/gto/preflop with Hero's two cards, Hero's position, and every preflop action before Hero. Pokerai API derives the spot and returns a JSON strategy distribution for that hand.

Updated Maintained by Pokerai API

Direct answer: authenticate with your API key, send hole_cards, positions.hero, and the complete preflop_actions sequence, and optionally select preflop_version. Read each item in strategy as a frequency, not as a recommended move.

Quick facts

EndpointPOST /v1/gto/preflop
Required inputhole_cards, positions.hero, and preflop_actions
OutputThe derived situation, mixed strategy[], and current quota usage
QuotaEach call charges 1 general presolved lookup; it does not use real-time solve quota
Intended useTraining, study, coaching, hand review, and research — never real-money RTA

Build the preflop request

The action line is explicit and ordered. Start with the blind posts, include every fold, call, and raise before Hero, and stop before Hero acts. Do not include Hero in preflop_actions.

FieldWhat to send
hole_cardsExactly two cards as one unseparated string, such as "AhKh".
positions.heroHero's seat in the current 6-max position set: SB, BB, UTG, MP, CO, or BTN.
preflop_actionsThe complete sequence before Hero. Each item has position and action; non-fold actions include the newly invested amount in BB, not a running total.
preflop_versionOptional chart-set ID. Omit it for the platform default, or use an ID returned by GET /v1/gto/preflop/versions.

Minimal curl request

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"MP"},"preflop_version":"6max_RC_100bb_200NL",
       "preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},
                          {"position":"BB","action":"big blind","amount":1},
                          {"position":"UTG","action":"raise","amount":3}]}'

Read the real response

This captured response matches the request above: Hero has AhKh in MP facing a UTG open. situation is derived from the action line, and quota reports this key's monthly usage.

{"hole_cards": "AhKh", "situation": "Raise", "strategy": [{"action": "raise", "frequency": 1, "amount_bb": 9, "sizing_pot": 0.8}], "quota": {"used": 7, "limit": 100}}

How mixed frequency works

Each frequency is a probability from 0 to 1, and the action frequencies for the hand normally sum to about 1. Some hands are pure, as in the response above; others are genuinely mixed.

For example, a captured response for 9h9s in MP facing a 2.5BB UTG open returned fold 0.254, call 0.106, and raise 0.64. That means 25.4% fold, 10.6% call, and 64% raise. The API exposes the distribution; it does not promise or choose a recommended action.

What amount_bb means

For a returned raise, amount_bb is the absolute amount to raise to in big blinds. It is not the incremental amount used inside the request's action history.

Raises before HeroDerived spotamount_bb
0Open3
13-bet9
24-bet25
3 or more5-bet+100 with allin: true

Choose preflop_version safely

The optional preflop_version selects a preflop chart set, and the same spot can have different frequencies across versions. The example uses 6max_RC_100bb_200NL; omitting the field selects the platform default.

Treat GET /v1/gto/preflop/versions as the authoritative discovery endpoint. Use an ID it returns instead of assuming that today's IDs, stack depths, or formats are permanent.

Quota and retries

A preflop lookup consumes 1 general presolved quota. The response's quota.used and quota.limit show the current monthly counter for that API key; usage is also visible in the dashboard.

Do not retry a quota-exhausted request. Wait for the monthly reset or change the available quota; reserve retry logic for transient failures documented by the API.

Common errors

HTTPErrorCause and fix
400invalid_hole_cardsSend exactly two valid cards in hole_cards.
400invalid_positions / invalid_actionsUse a documented Hero position and a complete, legal action sequence that starts with the blind posts.
400unsupported_preflop_versionRefresh GET /v1/gto/preflop/versions and pass one of the returned IDs.
401missing_api_key / invalid_api_keySend a valid API key in the Authorization: Bearer header.
404no_solutionThe requested spot has no presolved data; verify or change the spot instead of retrying unchanged.
429quota_exceededThe monthly general quota is exhausted; an immediate retry will not help.

When to use this — and when not to

Use preflop strategy lookups in trainers, study tools, coaching workflows, hand-review queues, research, and offline agent analysis. Store the returned frequencies with the version and input spot so a review remains reproducible.

Do not use Pokerai API for real-time assistance at real-money tables, and do not turn mixed output into a claim that one move is guaranteed or recommended. Real-time assistance at real-money tables is prohibited. See the Terms.

Do not use Pokerai API for real-time assistance at real-money tables, and do not turn mixed output into a claim that one move is guaranteed or recommended. Real-money RTA is prohibited by the Terms.

Reference, SDK, and next steps