Read the status of a Agent

GET

/apis/nodus.dev/v1/namespaces/{namespace}/agents/{name}/status

const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/agents/example/status';
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/agents/example/status

Parameters

Path Parameters

namespace

required

string

The project.

name

required

string

The object’s name.

Responses

200

application/json

Agent is a durable agent definition: a system prompt, the Claude access it runs on and its cost cap. Each run executes the agent loop in its own Sandbox, and a change to the spec applies to the runs created after it.

object

apiVersion

string

kind

string

metadata

object

annotations

object

key

additional properties

string

creationTimestamp

string

deletionGracePeriodSeconds

integer format: int64

deletionTimestamp

string

finalizers

Array<string>

nullable

generateName

string

generation

integer format: int64

labels

object

key

additional properties

string

managedFields

Array<object>

nullable

object

apiVersion

string

fieldsType

string

fieldsV1

object

key

additional properties

manager

string

operation

string

subresource

string

time

string

name

string

namespace

string

ownerReferences

Array<object>

nullable

object

apiVersion

required

string

blockOwnerDeletion

boolean

controller

boolean

kind

required

string

name

required

string

uid

required

string

resourceVersion

string

selfLink

string

uid

string

spec

required

AgentSpec describes an Agent.

object

env

Env configures tool processes. Store credentials in project Secrets and use valueFrom.secretKeyRef.

Array<object>

nullable

EnvVar is one environment variable: a literal value or a Secret key.

object

name

required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string

value

Value is the literal value.

string

valueFrom

EnvVarSource names where an env value comes from.

object

secretKeyRef

SecretKeySelector selects one key of a Secret.

object

key

required

Key is the key within it.

string

name

required

Name is the Secret.

string

image

Image is the Sandbox image each run’s tools execute in; nodus/agent-tools when empty.

string

maxParallelAgents

MaxParallelAgents caps concurrent subagents in one shared sandbox, from 1 to 32; 8 when zero. The parent chooses the actual count for each task within this ceiling.

integer format: int32

maxTokens

MaxTokens bounds the output of each model call; 8192 when zero.

integer format: int64

maxToolCalls

MaxToolCalls bounds the tool calls of one turn; 50 when zero.

integer format: int32

model

AgentModel is spec.model.

object

access

Access is Nodus (legacy managed Claude, the default), OnDemand or BYOK. Hosted is reserved and rejected.

string

apiKeyField

APIKeyField selects a key in APIKeySecret; defaults to ANTHROPIC_API_KEY or OPENAI_API_KEY. A Secret containing exactly one value may use any field name.

string

apiKeySecret

APIKeySecret names the project Secret holding the model API key. Required for BYOK.

string

baseURL

BaseURL is an HTTPS API base including /v1, for BYOK only. Empty uses the protocol’s official API.

string

families

Families limits the Claude families the router may pick (haiku, sonnet, opus, fable); every family when empty. Access Nodus only.

Array<string>

nullable

name

Name selects an OnDemand catalog model (or endpoint/name) or a BYOK model id. Required for OnDemand and OpenAI BYOK; Anthropic BYOK defaults to Sonnet.

string

port

Port is reserved for future hosted inference; currently rejected.

integer format: int32

protocol

Protocol is Anthropic or OpenAI. BYOK defaults to Anthropic.

string

sandbox

Sandbox is reserved for future hosted inference; currently rejected.

string

workspace

Workspace is reserved for future hosted inference; currently rejected.

string

network

Network sets egress for the container.

object

egress

Egress is the outbound network policy.

object

allow

Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).

Array<string>

nullable

policy

Policy is Deny, AllowList or Open.

string

presets

Presets add curated host lists such as python-packages or huggingface.

Array<string>

nullable

perRunMaxCostUSD

PerRunMaxCostUSD is the model cost cap of each Nodus or OnDemand run, 0.01 to 1000; “1.00” when empty. A run is created with the cap its Agent has at that moment and keeps it. Before each model call the run checks that the call at its largest, the whole request as input and spec.maxTokens of output, fits under the cap; when it does not, the run waits (MaxCostReached) and makes no more calls. BYOK has no Nodus token charge; the provider account has separate budgets.

string

secrets

Secrets mounts project Secrets in the shared sandbox, using the Sandbox secret delivery contract.

Array<object>

nullable

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object

name

required

Name is the Secret.

string

version

Version pins a version; unset pins the latest at admission.

integer format: int32

state

State is Running (the default) or Stopped, which refuses new runs and leaves the queued ones alone.

string

system

System is the system prompt of every turn, up to 64 KiB.

string

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": {
    "env": [
      {
        "name": "example",
        "value": "example",
        "valueFrom": {
          "secretKeyRef": {
            "key": "example",
            "name": "example"
          }
        }
      }
    ],
    "image": "example",
    "maxParallelAgents": 1,
    "maxTokens": 1,
    "maxToolCalls": 1,
    "model": {
      "access": "example",
      "apiKeyField": "example",
      "apiKeySecret": "example",
      "baseURL": "example",
      "families": [
        "example"
      ],
      "name": "example",
      "port": 1,
      "protocol": "example",
      "sandbox": "example",
      "workspace": "example"
    },
    "network": {
      "egress": {
        "allow": [
          "example"
        ],
        "policy": "example",
        "presets": [
          "example"
        ]
      }
    },
    "perRunMaxCostUSD": "example",
    "secrets": [
      {
        "name": "example",
        "version": 1
      }
    ],
    "state": "example",
    "system": "example"
  }
}

default

An error: a metav1.Status whose reason is a registered code.

application/json

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

apiVersion

string

code

integer format: int32

details

object

causes

Array<object>

nullable

object

field

string

message

string

reason

string

group

string

kind

string

name

string

retryAfterSeconds

integer format: int32

uid

string

docs

Docs is the URL of the code’s docs page.

string

fix

Fix says what to do next, for example a CLI command or the field to change.

string

kind

string

message

string

metadata

object

continue

string

remainingItemCount

integer format: int64

resourceVersion

string

selfLink

string

shardInfo

object

selector

required

string

reason

string

requestId

RequestID identifies the request in logs and support tickets.

string

status

string

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"
}

Read the status of a Agent

Parameters

Path Parameters

Responses

200

Example generated

default

Example generated

Example ^generated

Example ^generated