---
title: "Get next pair to validate (with stats)"
method: GET
path: "/v1/validations/next"
tags: ["simple"]
---

# Get next pair to validate (with stats)

`GET /v1/validations/next`

## Request

- Base URL: `https://alive-api.alphakek.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://alive-api.alphakek.ai/v1/validations/next`
- Auth: none declared

Always 200. Returns ``{pair, stats}`` where ``pair`` is the next unvalidated pair across all benches (auto-selected) or ``null`` when none are available, and ``stats`` always reflects the calling verifier — lifetime ``verified`` count, ``eligible_remaining``, and a ``reason`` enum that explains *why* ``pair`` is ``null`` (saturated_self / saturated_validated / none_yet). Loop until ``pair`` is ``null``.

## Query parameters

- `bench` string, nullable: Filter by bench token address

## Response `200`

Successful Response

- NextValidationResponse: Combined pair + stats payload returned from ``GET /v1/validations/next``. Always 200 with both fields. ``pair`` is ``null`` when no pair is available (the SDK should treat this as the loop-exit condition); ``stats`` always reflects the current verifier and explains *why* the pair is null. Folding stats into this response avoids the race window of a separate /stats endpoint and lets clients handle the "all caught up" case in one round-trip.
  - `pair` ValidationPair, required: The pair fields previously returned bare from /v1/validations/next. Now nested under ``NextValidationResponse.pair`` so the response can also carry stats when pair is ``None``.
    - `challenge_id` string, required
    - `challenge_title` string, required
    - `challenge_description` string, required
    - `solution_a_id` string, required
    - `solution_a_text` string, required
    - `solution_b_id` string, required
    - `solution_b_text` string, required
    - `token_address` string, required
    - `token_name` string, required
    - `token_symbol` string, required
    - `token_conviction` string, nullable
  - `stats` ValidationStats, required: Per-verifier counts that explain *why* ``pair`` is ``None`` (or just give a running tally when it isn't). Always present on ``NextValidationResponse`` so the webapp/SDK never need a second round-trip.
    - `verified` integer, required: Pairs this wallet has reviewed (voted or skipped) lifetime.
    - `eligible_remaining` integer, required: Pairs the wallet could fetch right now via /v1/validations/next. Exposed for SDK/CLI consumers (e.g. an 'X pairs remaining' indicator); the webapp doesn't currently display it but ``derive_validation_reason`` already needs the count, so the field is free to expose.
    - `reason` 'available' | 'saturated_self' | 'saturated_validated' | 'none_yet', required: Why the pool is in its current state: 'available' = ``eligible_remaining > 0`` at stats-query time (usually but not always matches ``pair != null`` — the pair and stats queries aren't transactional, so a concurrent verification between them can produce either ``pair=null, reason=available`` or ``pair!=null, reason=saturated_validated``); 'saturated_self' = empty because the verifier authored one side of every remaining pair (top contributors hit this); 'saturated_validated' = verifier has reviewed every pair they're eligible for; 'none_yet' = no eligible pairs exist for this wallet and the wallet has no verification history (covers brand-new system, deactivated benches, or all challenges still below the submission threshold).

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `b6d96e7673dc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/alphakek-ai/apis/aikek-api/changes/v1/validations/next/get.md)

---

[API](https://skmtc.dev/alphakek-ai/apis/aikek-api.md) - [All operations](https://skmtc.dev/alphakek-ai/apis/aikek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/alphakek-ai/apis/aikek-api/revisions/b6d96e7673dc?raw)