Ping

Endpoint health probes.

Methods on this page are called through client.ping.

client.ping.once

client.ping.once(request: PingOnceRequest, requestOptions?: RequestOptions): Promise<PingResultResponseShape>

Runs a single ping probe and returns the probe result.

HTTP: POST /v1/ping:once

Parameters

Parameter	Type	Description
`request`	`PingOnceRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<PingResultResponseShape>

Example

const ping = await client.ping.once({
  targetId: "your-embedder-id",
  targetTypeHint: "EMBEDDER",
  payloadType: "TEXT",
  payload: "hello",
});
console.log(ping.ok);

client.ping.stream

client.ping.stream(request: PingStreamParams, requestOptions?: RequestOptions): AsyncIterable<PingEventResponseShape>

Opens a streaming ping session and returns per-probe results plus a terminal summary.

HTTP: POST /v1/ping:stream

Parameters

Parameter	Type	Description
`request`	`PingStreamParams`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: AsyncIterable<PingEventResponseShape>

Example

for await (const event of client.ping.stream({
  targetId: "your-embedder-id",
  targetTypeHint: "EMBEDDER",
  count: 3,
  payloadType: "TEXT",
  payload: "hello",
})) {
  console.log(event.result?.ok);
}

Data Models

Enum Values

PingPayloadType

PAYLOAD_TYPE_UNSPECIFIED, TEXT, JSON, BINARY

PingTargetType

TARGET_TYPE_UNSPECIFIED, EMBEDDER, RERANKER, LLM

Interfaces

PingEndpointInfo

Resolved endpoint metadata for ping responses

Field	Type	Required	Description
`targetType`	`PingTargetType`	yes	Resolved resource type
`targetId`	`string`	yes	Target resource ID (UUID)
`resolvedEndpoint`	`string`	yes	Fully resolved endpoint URL used for the probe
`provider`	`string`	yes	Provider name backing the resource
`modelIdentifier`	`string`	yes	Provider-specific model identifier

PingEvent

Streaming event from a ping session

Field	Type	Required	Description
`result`	`PingResult \| null`	no	Probe result event
`summary`	`PingSummary \| null`	no	Summary emitted at session completion
`notice`	`PingNotice \| null`	no	Non-fatal notice emitted during session

PingNotice

Non-fatal notice emitted during a ping session

Field	Type	Required	Description
`code`	`string`	yes	Machine-readable notice identifier
`message`	`string`	yes	Human-readable notice message
`details`	`Record<string, string> \| null`	no	Additional contextual details

PingOnceRequest

Request payload for a single ping probe

Field	Type	Required	Description
`targetId`	`string`	yes	Target resource ID (UUID)
`targetTypeHint`	`PingTargetType \| null`	no	Optional hint for the target resource type
`payloadType`	`PingPayloadType \| null`	no	Desired payload type (defaults to provider-specific value)
`payload`	`string \| null`	no	Explicit UTF-8 payload to send with the probe (mutually exclusive with payloadSizeBytes)
`payloadSizeBytes`	`number \| null`	no	Synthetic payload size in bytes (mutually exclusive with payload)
`timeoutMs`	`number \| null`	no	Per-probe timeout in milliseconds (0 uses server default)

PingResult

Result from an individual ping probe

Field	Type	Required	Description
`endpoint`	`PingEndpointInfo`	yes	Resolved endpoint metadata for the target
`seq`	`number`	yes	Sequential probe number (1-based)
`bytesSent`	`number`	yes	Payload bytes transmitted
`bytesReceived`	`number`	yes	Payload bytes received
`ok`	`boolean`	yes	True when the provider responded successfully within the timeout
`httpStatus`	`number`	yes	Provider HTTP status code or equivalent transport status
`errorMessage`	`string \| null`	no	Human-readable error message when ok=false
`rttMs`	`number`	yes	Observed round-trip latency in milliseconds
`timing`	`PingTiming`	yes	Raw timing data recorded on the server
`metadata`	`Record<string, string> \| null`	no	Additional provider metadata (request IDs, throttling signals, etc.)

PingStreamRequest

Request payload for a streaming ping session

Field	Type	Required	Description
`targetId`	`string`	yes	Target resource ID (UUID)
`targetTypeHint`	`PingTargetType \| null`	no	Optional hint for the target resource type
`count`	`number \| null`	no	Number of probes to run (0 uses server default)
`intervalMs`	`number \| null`	no	Delay between probes in milliseconds (0 uses server default)
`timeoutMs`	`number \| null`	no	Per-probe timeout in milliseconds (0 uses server default)
`payloadType`	`PingPayloadType \| null`	no	Desired payload type (defaults to provider-specific value)
`payload`	`string \| null`	no	Explicit UTF-8 payload to send with each probe (mutually exclusive with payloadSizeBytes)
`payloadSizeBytes`	`number \| null`	no	Synthetic payload size in bytes (mutually exclusive with payload)
`maxInFlight`	`number \| null`	no	Maximum concurrent probes (defaults to 1)
`jitter`	`boolean \| null`	no	Add jitter to probe scheduling
`labels`	`Record<string, string> \| null`	no	Optional labels to attach to the ping session

PingSummary

Summary emitted at the end of a ping session

Field	Type	Required	Description
`endpoint`	`PingEndpointInfo`	yes	Endpoint metadata copied from the final probe
`requests`	`number`	yes	Total number of probes scheduled
`responses`	`number`	yes	Number of responses received (including timeouts/errors)
`ok`	`number`	yes	Count of probes that succeeded
`timeouts`	`number`	yes	Count of probes that exceeded the timeout
`errors`	`number`	yes	Count of probes that failed for other reasons
`rttMinMs`	`number`	yes	Minimum observed round-trip latency (ms)
`rttAvgMs`	`number`	yes	Average observed round-trip latency (ms)
`rttP50Ms`	`number`	yes	Median (p50) round-trip latency (ms)
`rttP90Ms`	`number`	yes	90th percentile round-trip latency (ms)
`rttP99Ms`	`number`	yes	99th percentile round-trip latency (ms)
`rttMaxMs`	`number`	yes	Maximum observed round-trip latency (ms)
`requestsPerSecond`	`number`	yes	Effective request throughput across the session
`bytesPerSecond`	`number`	yes	Aggregate bytes per second (send + receive)
`appliedLimits`	`Record<string, string> \| null`	no	Resource limits applied by the server

PingTiming

Timing information captured during a ping probe

Field	Type	Required	Description
`clientSendTimeUnixNanos`	`number`	yes	Client send time (Unix epoch nanoseconds)
`serverReceivedTimeUnixNanos`	`number`	yes	Server received time (Unix epoch nanoseconds)
`serverSendTimeUnixNanos`	`number`	yes	Server send time (Unix epoch nanoseconds)
`clientReceiveTimeUnixNanos`	`number`	yes	Client receive time (Unix epoch nanoseconds)

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

PingEndpointInfoResponseShape

Field	Type	Required	Description
`targetType`	`PingTargetType \| null`	yes	Resolved resource type
`targetId`	`string`	yes	Target resource ID (UUID)
`resolvedEndpoint`	`string`	yes	Fully resolved endpoint URL used for the probe
`provider`	`string`	yes	Provider name backing the resource
`modelIdentifier`	`string`	yes	Provider-specific model identifier

PingEventResponseShape

Type constraint: PingEventResponseShape = RequireExactlyOne<PingEventResponseShapeBase, "notice" \| "result" \| "summary">

Field	Type	Required	Description
`result`	`PingResultResponseShape \| null`	no	Probe result event
`summary`	`PingSummaryResponseShape \| null`	no	Summary emitted at session completion
`notice`	`PingNoticeResponseShape \| null`	no	Non-fatal notice emitted during session

PingNoticeResponseShape

Field	Type	Required	Description
`code`	`string`	yes	Machine-readable notice identifier
`message`	`string`	yes	Human-readable notice message
`details`	`Record<string, string> \| null`	no	Additional contextual details

PingResultResponseShape

Field	Type	Required	Description
`endpoint`	`PingEndpointInfoResponseShape`	yes	Resolved endpoint metadata for the target
`seq`	`number`	yes	Sequential probe number (1-based)
`bytesSent`	`number`	yes	Payload bytes transmitted
`bytesReceived`	`number`	yes	Payload bytes received
`ok`	`boolean`	yes	True when the provider responded successfully within the timeout
`httpStatus`	`number`	yes	Provider HTTP status code or equivalent transport status
`errorMessage`	`string \| null`	no	Human-readable error message when ok=false
`rttMs`	`number`	yes	Observed round-trip latency in milliseconds
`timing`	`PingTimingResponseShape`	yes	Raw timing data recorded on the server
`metadata`	`Record<string, string> \| null`	no	Additional provider metadata (request IDs, throttling signals, etc.)

PingSummaryResponseShape

Field	Type	Required	Description
`endpoint`	`PingEndpointInfoResponseShape`	yes	Endpoint metadata copied from the final probe
`requests`	`number`	yes	Total number of probes scheduled
`responses`	`number`	yes	Number of responses received (including timeouts/errors)
`ok`	`number`	yes	Count of probes that succeeded
`timeouts`	`number`	yes	Count of probes that exceeded the timeout
`errors`	`number`	yes	Count of probes that failed for other reasons
`rttMinMs`	`number`	yes	Minimum observed round-trip latency (ms)
`rttAvgMs`	`number`	yes	Average observed round-trip latency (ms)
`rttP50Ms`	`number`	yes	Median (p50) round-trip latency (ms)
`rttP90Ms`	`number`	yes	90th percentile round-trip latency (ms)
`rttP99Ms`	`number`	yes	99th percentile round-trip latency (ms)
`rttMaxMs`	`number`	yes	Maximum observed round-trip latency (ms)
`requestsPerSecond`	`number`	yes	Effective request throughput across the session
`bytesPerSecond`	`number`	yes	Aggregate bytes per second (send + receive)
`appliedLimits`	`Record<string, string> \| null`	no	Resource limits applied by the server

PingTimingResponseShape

Field	Type	Required	Description
`clientSendTimeUnixNanos`	`number`	yes	Client send time (Unix epoch nanoseconds)
`serverReceivedTimeUnixNanos`	`number`	yes	Server received time (Unix epoch nanoseconds)
`serverSendTimeUnixNanos`	`number`	yes	Server send time (Unix epoch nanoseconds)
`clientReceiveTimeUnixNanos`	`number`	yes	Client receive time (Unix epoch nanoseconds)

Ping

On this page