About this endpoint
What it does
Analyses one Go position with the KataGo engine and returns the best candidate moves, the expected line of play after each, Black's win probability and score lead, and — on request — a predicted ownership map of the board. Send the move history (and any setup stones) for a board of 2×2 up to 19×19; win rates and scores are always reported from Black's side, even when White is to move.
Shared capacity is 10 requests per minute, 10,000 per UTC day and 3 at once across all buyers. A cold start can take 20–40 seconds, so use a 90-second client timeout and honour Retry-After on 429. Illegal input (bad coordinates, occupied points, ko or suicide where the rules forbid it) returns 400; a body over 64 KiB returns 413.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query | object | Yes | Wrapper for the position; every field below goes inside it. |
query.id | string | Yes | Your own label for this request, 1–128 printable characters; returned as results[].id. |
query.moves | array | Yes | Moves played so far, in order, up to 2,000. Each is [colour, coordinate]: colour B (Black) or W (White); coordinate in GTP form — column A–T skipping I, then row from 1 at the bottom (e.g. D4) — or pass. |
query.rules | string | Yes | Scoring and ko ruleset — chinese, japanese, korean, aga (American Go Association), tromp-taylor, new-zealand, chinese-ogs (Chinese as played on OGS), stone-scoring, ancient-territory, bga (British Go Association), aga-button (AGA with the pass button). |
query.boardXSize | integer | Yes | Board width in points, 2–19. |
query.boardYSize | integer | Yes | Board height in points, 2–19. |
query.maxVisits | integer | Yes | Search effort, 16–1,000 visits. Higher is stronger and slower; the actual count can slightly exceed it and is returned in usage.visits. |
query.komi | number | No | Points given to White, −400 to 400 in steps of 0.5. Default 7.5. |
query.initialStones | array | No | Stones already on the board before moves, up to 361, as [colour, coordinate] pairs. No pass, no repeated points. Default []. |
query.initialPlayer | string | No | Who moves first in moves — B (Black) or W (White, e.g. after handicap stones). Default B. |
query.includeOwnership | boolean | No | Return results[].ownership. Default false. |
query.includeOwnershipStdev | boolean | No | Return results[].ownershipStdev. Default false. |
query.includeMovesOwnership | boolean | No | Return ownership on every candidate move. Default false. |
query.includeMovesOwnershipStdev | boolean | No | Return ownershipStdev on every candidate move. Default false. |
query.includePolicy | boolean | No | Return results[].policy. Default false. |
query.includePVVisits | boolean | No | Return pvVisits and pvEdgeVisits on every candidate move. Default false. |
Response
A JSON object holding one result for your position, with candidate moves ranked best first and the resources the search used.
| Field | Type | Description |
|---|---|---|
id | string | Job identifier ApyHub's upstream assigns to this analysis (a UUID); differs on every call. |
results | array | Analysis results — one object for the position you sent. |
results[].id | string | Your query.id, echoed back unchanged. |
results[].isDuringSearch | boolean | Always false here: the result is the finished search, not a partial update. |
results[].turnNumber | integer | Number of moves from query.moves that were played before the analysed position. |
results[].rootInfo | object | Evaluation of the analysed position itself. |
results[].rootInfo.currentPlayer | string | Colour to move in the analysed position — B (Black) or W (White). |
results[].rootInfo.visits | integer | Search visits actually completed on the position. |
results[].rootInfo.winrate | number | Probability Black wins, 0 to 1 — always from Black's side, even when White is to move. |
results[].rootInfo.scoreLead | number | Expected Black lead in points (komi included); negative means White leads. |
results[].rootInfo.scoreSelfplay | number | Expected final Black margin in points if the engine played the game out against itself; negative favours White. |
results[].rootInfo.scoreStdev | number | Standard deviation of the expected score, in points — how uncertain the score estimate is. |
results[].rootInfo.utility | number | Engine's combined win/score value used to rank positions, from Black's side; higher is better for Black. |
results[].rootInfo.weight | number | Total search weight behind the evaluation (visits adjusted for confidence). |
results[].rootInfo.rawWinrate | number | Neural network's Black win probability before any search, 0 to 1. |
results[].rootInfo.rawLead | number | Neural network's expected Black lead in points before any search. |
results[].rootInfo.rawScoreSelfplay | number | Neural network's expected self-play Black margin in points before any search. |
results[].rootInfo.rawScoreSelfplayStdev | number | Standard deviation of rawScoreSelfplay, in points. |
results[].rootInfo.rawNoResultProb | number | Neural network's probability the game ends with no result (for example a triple ko), 0 to 1. |
results[].rootInfo.rawStWrError | number | Neural network's own estimate of its short-term win-rate error. |
results[].rootInfo.rawStScoreError | number | Neural network's own estimate of its short-term score error, in points. |
results[].rootInfo.rawVarTimeLeft | number | Neural network's estimate of how much the evaluation can still swing before the game ends. |
results[].rootInfo.thisHash | string | Hex hash identifying this exact position and player to move. |
results[].rootInfo.symHash | string | Hex hash that is the same for this position and all its rotations and reflections. |
results[].moveInfos | array | Candidate moves for the player to move, best first. |
results[].moveInfos[].move | string | Candidate move as a GTP coordinate (column letter A–T without I, then row number, e.g. Q4) or pass. |
results[].moveInfos[].order | integer | Rank of the candidate, 0 = best. |
results[].moveInfos[].isSymmetryOf | string | Present only when this move is a mirror/rotation of a move listed earlier; names that move. Its numbers are copied from it. |
results[].moveInfos[].visits | integer | Search visits spent on this candidate. |
results[].moveInfos[].edgeVisits | integer | Visits the root gave to this move directly; can differ from visits when positions repeat in the tree. |
results[].moveInfos[].weight | number | Search weight behind this candidate's numbers. |
results[].moveInfos[].edgeWeight | number | Search weight the root gave to this move directly. |
results[].moveInfos[].winrate | number | Probability Black wins after this move, 0 to 1, from Black's side. |
results[].moveInfos[].lcb | number | Lower confidence bound of winrate (Black's side) — a cautious win-rate estimate. |
results[].moveInfos[].scoreLead | number | Expected Black lead in points after this move; negative means White leads. |
results[].moveInfos[].scoreMean | number | Same value as scoreLead, kept for older clients. |
results[].moveInfos[].scoreSelfplay | number | Expected final Black margin in points after this move if the engine played itself out. |
results[].moveInfos[].scoreStdev | number | Standard deviation of the expected score after this move, in points. |
results[].moveInfos[].utility | number | Engine's combined win/score value for this move, from Black's side. |
results[].moveInfos[].utilityLcb | number | Lower confidence bound of utility. |
results[].moveInfos[].prior | number | Neural network's probability, before search, that this is the best move, 0 to 1. |
results[].moveInfos[].playSelectionValue | number | Score the engine ranks candidates by; higher is preferred. |
results[].moveInfos[].pv | array | Principal variation: the expected best line of play starting with this move, as GTP coordinates. |
results[].moveInfos[].pvVisits | array | Only with includePVVisits: search visits behind each move of pv, same order. |
results[].moveInfos[].pvEdgeVisits | array | Only with includePVVisits: direct visits given to each move of pv, same order. |
results[].moveInfos[].ownership | array | Only with includeMovesOwnership: predicted final ownership after this move — 361 values (one per board point, row-major from the top-left, A19 → T1 on 19×19), each −1 (White owns) to +1 (Black owns). |
results[].moveInfos[].ownershipStdev | array | Only with includeMovesOwnershipStdev: uncertainty of each ownership value, 0 to 1, same order. |
results[].ownership | array | Only with includeOwnership: predicted final ownership of the position — 361 values (one per board point, row-major from the top-left, A19 → T1 on 19×19), each −1 (White owns) to +1 (Black owns). |
results[].ownershipStdev | array | Only with includeOwnershipStdev: uncertainty of each ownership value, 0 to 1, same order. |
results[].policy | array | Only with includePolicy: neural network move probabilities — one per board point (row-major from the top-left) then one for pass (362 on 19×19); -1 marks an illegal point. |
usage | object | What the call consumed. |
usage.visits | integer | Search visits actually completed; can slightly exceed maxVisits because the search runs in parallel. |
usage.queuedMs | number | Time the request waited for an engine, in milliseconds. |
usage.executionMs | number | Engine compute time in milliseconds, excluding HTTP transfer and cold starts. |
usage.preset | string | Analysis profile the engine ran (e.g. fast). |
usage.model | string | KataGo neural network that produced the analysis (e.g. kata1-tf2-b10c384-s2941M-d5872M). |
usage.gpuName | string | GPU model the analysis ran on. |


