Read a AgentGroup
const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/agentgroups/example';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/apis/nodus.dev/v1/namespaces/example/agentgroups/exampleParameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”The project.
The object’s name.
Responses
Section titled “ Responses ”OK
AgentGroup runs many AgentRuns of one Agent in parallel: a concurrency limit, a dependency graph, a shared cost cap and one cancel over its member runs. Members are AgentRuns created with spec.group, one per task, singly or as an AgentRunList of up to 100.
object
object
object
object
object
object
object
AgentGroupSpec describes an AgentGroup.
object
Agent names the Agent every member run runs: an Agent in the project, or a template in project nodus.
AgentGroupEvaluation selects a reproducible Environment task manifest. Compute for the agent and grader Sandboxes is billed separately from maxCostUSD and remains subject to project and organization budgets.
object
Environment is a project or nodus/name@version reference, resolved to an immutable image digest.
Repetitions runs each task this many times; tasks times repetitions must be at most 100.
Seed selects the deterministic task manifest.
Split is train or test; test by default.
Tasks takes the first N tasks in manifest order, 1 to 100.
Timeout bounds the batch from creation, including manifest preparation and queued time; 30m by default, 1m to 24h.
AgentGroupLimits is spec.limits.
object
MaxActive is how many member runs may run at once, 1 to 1000; 10 when zero.
MaxPending is how many unfinished member runs the group admits, 1 to 10000; 10000 when zero.
MaxCostUSD is one cap on the Claude usage (model and routing calls) of every member run together; none when empty. A member run starts only while what the group has spent, plus the per-run cost caps of its started unfinished runs, plus this run’s cap fits under it, so the members together never spend more on Claude. The Sandbox each run works in is billed on its own and is not counted. It can only be raised.
Sealed closes the group to new runs. It goes from false to true only; a group finishes once it is sealed and every member run is terminal.
State is Running (the default) or the cancel state, which cancels every unfinished member run.
AgentGroupStatus is what Nodus observed about an AgentGroup.
object
BlockedReasons says why queued member runs have not started, with how many wait for each reason.
AgentGroupBlocked is one entry of status.blockedReasons.
object
Count is how many queued member runs wait for it.
Reason is DependencyWait, MaxActiveReached or MaxCostReached.
Cleanup is Pending while a canceled or finished group still has unfinished member runs, then Complete. A terminal member run holds no Sandbox.
CompletionTime is when the group reached a terminal phase.
Cost is status.cost on every kind that spends money. It is a display copy of the ledger: amounts are decimal USD strings, and nothing is charged from these fields.
object
CostSegments splits a charge by billing segment.
object
BootUSD is the charge from the start of billing until the program started.
CoveredByNodus lists the segments (Boot, Running, Restore, Teardown) with time Nodus paid for instead of charging it, such as the start and teardown of a run that failed because of Nodus.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningUSD is the charge while the program ran.
TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.
Final is true once the final charge has posted.
FundedUntilTime is when the current holds stop paying for the object.
HeldUSD is what is currently held for it.
LimitUSD is the object’s maxCostUSD, if it has one.
RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.
TotalUSD is what has been charged for this object so far.
AgentGroupCounts is status.counts.
object
Active runs are running.
The runs canceled by request or because a dependency did not succeed.
Failed runs failed.
Queued runs have not started: they wait for their dependencies, a free slot or room under the cost cap.
Succeeded runs finished their work.
Total is the number of member runs.
Waiting runs wait for a message or for funds; their Sandbox may remain allocated until cleanup.
AgentGroupEvaluationStatus contains only aggregate results and pinned provenance. Unscored failures are excluded from passRate and meanReward; a zero denominator leaves both absent.
object
AgentRevision is the revision pinned by every member.
AgentUID and AgentRevision identify the definition pinned by every member of this batch.
Canceled cases are not scored.
EnvironmentDigest is the resolved grading image, checked before every grading operation.
Failed counts failed member executions, which are not scored.
Incorrect counts scored wrong answers.
InfrastructureFailure counts unscored grader or environment failures.
Initialized says the fixed member batch has been created atomically.
InvalidOutput counts scored answers that failed the output contract.
MeanReward averages reward over scored verdicts; absent if none.
MissingAnswer counts completed runs without a readable answer and removed members.
PassRate is Correct divided by the number of scored verdicts; absent if none.
Passed counts Correct verdicts.
Pending counts cases not yet terminal or awaiting a verdict.
Total is the requested number of cases, including repetitions.
Message explains the phase in a sentence.
ObservedGeneration is the spec generation this status reflects.
Phase is Running until the group is sealed and every member run is terminal, then Succeeded, or Failed when a member run failed; the cancel state moves it through the canceling phase to the canceled one.
Reason is the machine-readable reason for the phase, such as RunsFailed.
StartTime is when the first member run started.
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "agent": "example", "evaluation": { "environment": "example", "repetitions": 1, "seed": 1, "split": "example", "tasks": 1, "timeout": "example" }, "limits": { "maxActive": 1, "maxPending": 1 }, "maxCostUSD": "example", "sealed": true, "state": "example" }, "status": { "blockedReasons": [ { "count": 1, "reason": "example" } ], "cleanup": "example", "completionTime": "example", "cost": { "bySegment": { "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreUSD": "example", "runningUSD": "example", "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "counts": { "active": 1, "cancelled": 1, "failed": 1, "queued": 1, "succeeded": 1, "total": 1, "waiting": 1 }, "evaluation": { "agentRevision": 1, "agentUID": "example", "cancelled": 1, "environmentDigest": "example", "failed": 1, "incorrect": 1, "infrastructureFailure": 1, "initialized": true, "invalidOutput": 1, "meanReward": 1, "missingAnswer": 1, "passRate": 1, "passed": 1, "pending": 1, "total": 1 }, "message": "example", "observedGeneration": 1, "phase": "example", "reason": "example", "startTime": "example" }}default
Section titled “ default ”An error: a metav1.Status whose reason is a registered code.
Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).
object
object
object
Docs is the URL of the code’s docs page.
Fix says what to do next, for example a CLI command or the field to change.
object
object
RequestID identifies the request in logs and support tickets.
Example generated
{ "apiVersion": "example", "code": 1, "details": { "causes": [ { "field": "example", "message": "example", "reason": "example" } ], "group": "example", "kind": "example", "name": "example", "retryAfterSeconds": 1, "uid": "example" }, "docs": "example", "fix": "example", "kind": "example", "message": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }, "reason": "example", "requestId": "example", "status": "example"}