Skip to main content
GET
List the groups of one step of a fine-tuning job

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

jobId
string<uuid>
required

Fine-tuning job id.

Query Parameters

split
enum<string>
required

The split to read.

Available options:
train,
eval
step
integer<int64>
required

The step to read.

Required range: 0 <= x <= 9007199254740991
spread
enum<string>

Only groups with no queued or running attempt and at least one scored attempt: mixed when the scored rewards differ, flat when they are all equal (a failed attempt is left out, as in training). Omit for every group.

Available options:
mixed,
flat
status
enum<string>

Only groups with at least one attempt in this status. Omit for every group.

Available options:
queued,
running,
done,
failed
q
string

Only groups whose task name contains this text, ignoring case. Omit for every group.

Required string length: 1 - 256
sortBy
enum<string>
default:group

What to order the groups by; the group index by default. task compares the raw task name byte by byte, so it is case-sensitive, unlike q. Groups without a score sort last for meanReward and stdReward in either direction, and ties fall back to ascending group index. Any other value is rejected with 400.

Available options:
group,
task,
meanReward,
stdReward
sortDirection
enum<string>
default:asc

Direction of sortBy. Any other value is rejected with 400.

Available options:
asc,
desc
limit
integer
default:20

Maximum groups to return. A page carries limit groups with all their attempts (up to 16 each), so on a 16-attempt held-out step a limit above about 100 can exceed 1 MiB; clients that cap a response at that size, such as MCP tool results, should page with a smaller limit.

Required range: 1 <= x <= 200
cursor
string

Opaque cursor from nextCursor. Pass it unchanged with the same parameters.

Response

OK

items
object[]
required

One page of the step's groups in the requested order; empty when none match or when the cursor is past the last match.

nextCursor
null | string
required

Opaque continuation cursor, or null on the last page. It holds an offset into an order computed from the step's current rollouts on every read, so while the step runs a walk through the pages can skip or repeat groups (as scores, statuses or new attempts move them between pages).

total
integer<int64>
required

Groups matching spread, status and q, across all pages, when this page was read.

Required range: 0 <= x <= 9007199254740991