Skip to main content
GET
JavaScript
An agent is a role. Its variations are the resumes. This endpoint shows you which resume is winning.

info arrives whether you ask or not

Unlike tool calls, where info is gated, this endpoint returns the full info block on every request. includeInfo changes nothing:
You get score, feedbackCount, assignments, memoryLayerAssignments, model, createdBy, and the four counts (toolCount, toolSetCount, subAgentCount, memoryLayerCount). Nothing to opt into.

score is a Beta posterior, not an average

score is the posterior mean of Beta(ts_alpha, ts_beta), on [0, 1], where 0.5 is neutral. A fresh variation with no feedback reads exactly 0.5, because the prior is Beta(1, 1). Each feedback score, on [-1.0, 1.0], moves it. Watch one variation take three:
The positive mass lands on ts_alpha and the negative on ts_beta, so the score is α / (α + β). That is why it is not an average. Three positives out of three reads 0.8, not 1.0: the prior keeps pulling toward neutral until enough evidence accumulates. A variation with one lucky win cannot outrank one with fifty solid ones, which is the entire point when weighted selection samples from these posteriors.
A feedback of exactly 0 is recorded and increments feedbackCount, but moves neither ts_alpha nor ts_beta. The score stays where it was. Use it to log a run you have no opinion about, not to signal mediocrity.
A score outside [-1.0, 1.0] is a 400.

Reading the leaderboard

sortOrder sorts by creation, not by score. Sort on the client when you want a ranking:
Read feedbackCount alongside score every time. A 0.5 with n=0 is an untested variation; a 0.5 with n=200 is a genuinely mediocre one. The number alone cannot tell them apart.

What each variation carries

Filter by labels to slice a large agent. limit sets a page size the SDK iterator pages past on its own.

Submit feedback

The [-1.0, 1.0] score that moves the posterior.

Create an agent

variationSelectionMode, and what WEIGHTED samples from.

Update a variation

Iterating a prompt, and why a zero value needs updateMask.

Add an assignment

What fills info.assignments.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

agentId
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

Query Parameters

limit
integer<int32>

Maximum number of results to return

cursor
string

Pagination cursor from previous response

sortOrder
string

Sort order for results (asc or desc by creation time)

includeInfo
boolean

When true, the info field on each returned variation is populated. Requests with this flag count more against your rate limit.

labels
string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

Response

OK

List agent variations response

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.