List or watch agentruns in every project
const url = 'https://example.com/apis/nodus.dev/v1/agentruns';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/agentrunsParameters
Section titled “ Parameters ”Query Parameters
Section titled “ Query Parameters ”Responses
Section titled “ Responses ”OK
object
AgentRun is one durable execution of an Agent revision: a conversation the agent works through turn by turn in its own Sandbox. A run survives restarts of Nodus: it replays its journal to where it stopped and never repeats a recorded model call or tool call.
object
object
object
object
object
object
object
AgentRunSpec describes an AgentRun. Everything is immutable after create except state.
object
Agent names an Agent in the project, or a template in project nodus.
Deadline fails the run with DeadlineExceeded when it passes.
DependsOn lists the task keys of the group the run starts after, each already in the group (or earlier in the same AgentRunList). The run is canceled when one of them fails or is canceled.
Group names the AgentGroup the run is a task of; the run then runs the group’s Agent, starts when the group releases it and is named
Input is the first prompt: a JSON string, or any JSON value, sent to the model as its text. Up to 256 KiB.
KeepAlive keeps the run Waiting for messages after each turn instead of succeeding.
State is the desired state: Running (the default) or the cancel state.
TaskKey is the run’s key in its group, a DNS label unique in the group; required with group.
AgentRunStatus is what Nodus observed about an AgentRun.
object
AgentRunAnswer is the final answer of a run.
object
Preview is the first 4 KiB of the answer.
SHA256 is the hex digest of the whole answer.
Size is the answer’s length in bytes.
CompletionTime is when the run 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.
Dispatches counts how many times a dispatcher picked the run up; more than one means it recovered.
Message explains the phase in a sentence.
ObservedGeneration is the spec generation this status reflects.
Phase is the lifecycle phase: Queued, Running, Waiting for a message or funds, then a terminal phase.
Reason is the machine-readable reason for the phase, such as WaitingForMessage or MaxCostReached.
Revision is the Agent revision the run pinned at admission.
Sandbox names the run’s Sandbox once it exists; it is deleted when the run ends.
StartTime is when the first dispatch started.
AgentRunSteps counts journal steps.
object
Total is the number of steps recorded.
Turns lists the run’s turns with the Claude model that served each.
AgentTurn is one prompt and the model’s work on it. The model is chosen once per turn and serves all of it.
object
CostUSD is the turn’s charge.
FallbackReason says why the router fell back to Sonnet.
Family is the Claude family the router chose (Nodus access).
InputTokens is the turn’s input token usage, cache reads and writes included.
Model is the Anthropic model that served every call of the turn.
ModelCalls is the number of model calls the turn made.
OutputTokens is the turn’s output token usage.
Prompt is “input” for the run’s input, or the key of the message that brought the prompt.
RoutedBy is jev, fallback (with fallbackReason) or fixed (BYOK).
ToolCalls is the number of commands the turn ran in the Sandbox.
object
object
Example generated
{ "apiVersion": "example", "items": [ { "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", "deadline": "example", "dependsOn": [ "example" ], "group": "example", "input": "example", "keepAlive": true, "state": "example", "taskKey": "example" }, "status": { "answer": { "preview": "example", "sha256": "example", "size": 1 }, "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" }, "dispatches": 1, "message": "example", "observedGeneration": 1, "phase": "example", "reason": "example", "revision": 1, "sandbox": "example", "startTime": "example", "steps": { "total": 1 }, "turns": [ { "costUSD": "example", "fallbackReason": "example", "family": "example", "inputTokens": 1, "model": "example", "modelCalls": 1, "outputTokens": 1, "prompt": "example", "routedBy": "example", "toolCalls": 1 } ] } } ], "kind": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "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"}