Get a node's simulator

GET

/nodes/{name}/simulation

const url = 'https://example.com/api/v1/nodes/example/simulation';
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/api/v1/nodes/example/simulation

The devices a simulator beside the node serves (each component with an endpoint placed on the node, within the caller’s component read scope), joined to the hits the server has seen and the simulator’s capabilities. Hits are live and per server process, not stored. Requires an all-scope node read. Gated by node:read.

Parameters

Path Parameters

name

required

The node’s unique name

string

The node’s unique name

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

capabilities

required

object

low_ports

required

boolean

net_admin

required

boolean

port_offset

required

integer format: int64

connected

required

A simulator beside this node pulled its device list recently.

boolean

devices

required

Array<object> | null

object

address

required

The host the component’s endpoints target.

string

component

required

The component’s name.

string

component_id

required

string

hits

required

Connections and requests the simulated device has answered since the server started.

integer format: int64

hits_by_protocol

required

object

key

additional properties

integer format: int64

impaired

required

Whether the simulator reported applying an impairment to the device in its latest batch.

boolean

impairment

What an operator has broken on the device; absent when healthy.

object

$schema

A URL to the JSON Schema for this object.

string format: uri

jitter_ms

Variation on the delay, in milliseconds; at most the latency

integer format: int64

latency_ms

Delay added to traffic toward the device, in milliseconds

integer format: int64

<= 10000

loss_pct

Share of packets toward the device dropped, in percent, to hundredths

number format: double

<= 100

rate_kbit

Bandwidth limit on the device’s link, both ways, in kilobits per second; 0 is unlimited

integer format: int64

<= 10000000

unplugged

Dark on every protocol: connects time out, datagrams and pings go unanswered

boolean

last_hit_at

string format: date-time

last_protocol

string

product

required

The component’s product; its name selects the simulator profile.

string

serving

required

Whether the simulator reported serving this component in its latest batch.

boolean

status

required

What the simulator is doing with the component, most urgent first: offline (its simulator stopped reporting), starting (added since the simulator’s last pull, or handed over moments ago), failed (handed to the simulator but not started), running.

string

Allowed values: running starting failed offline

impairments

required

Whether the simulator can apply impairments (and why not), its last apply error, and the devices it impairs.

object

available

required

boolean

error

string

impaired

Array<string> | null

reason

string

last_seen

string format: date-time

Example

{
  "$schema": "/api/v1/schemas/SimulationOutputBody.json",
  "devices": [
    {
      "impairment": {
        "$schema": "/api/v1/schemas/ImpairmentFields.json"
      },
      "status": "running"
    }
  ]
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

Example

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}