Ping a remote server

POST 
/node/:hostname/network/ping

Send a ping to a remote server to verify network connectivity.

Request

Path Parameters

hostname stringrequired

Possible values: non-empty

Target agent hostname, reserved routing value (_any, _all), or label selector (key:value).

application/json

Body

required

The server to ping.

address stringrequired

The IP address of the server to ping. Supports both IPv4 and IPv6. Also accepts @fact. references that are resolved agent-side.

Responses

200

Successful ping response.

application/json

Schema

Schema

job_id uuid

The job ID used to process this request.

results

object[]

required

Array [

hostname stringrequired

The hostname of the agent that executed the ping.

packets_sent integer

Number of packets sent.

packets_received integer

Number of packets received.

packet_loss double

Percentage of packet loss.

min_rtt string

Minimum round-trip time in Go time.Duration format.

avg_rtt string

Average round-trip time in Go time.Duration format.

max_rtt string

Maximum round-trip time in Go time.Duration format.

changed boolean

Whether the operation modified system state.

error string

Error message if the agent failed.

]

Example (from schema)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "hostname": "string",
      "packets_sent": 4,
      "packets_received": 4,
      "packet_loss": 0,
      "min_rtt": "14.637103ms",
      "avg_rtt": "18.647498ms",
      "max_rtt": "24.309240ms",
      "changed": true,
      "error": "string"
    }
  ]
}

400

Invalid request payload.

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

401

Unauthorized - API key required

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

403

Forbidden - Insufficient permissions

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

500

Error performing the ping operation.

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

Loading...