Ping

Methods on this page are called as client.ping.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Run a single ping probe

Runs a single ping probe and returns the probe result.

• target_id (str, format: uuid) — Target resource ID (UUID)
• payload (str, optional) — Explicit UTF-8 payload to send with the probe (mutually exclusive with payload_size_bytes)
• payload_size_bytes (int, format: int32, optional) — Synthetic payload size in bytes (mutually exclusive with payload)
• payload_type (PingPayloadType, optional) — Desired payload type (defaults to provider-specific value)
• target_type_hint (PingTargetType, optional) — Optional hint for the target resource type
• timeout_ms (int, format: int32, optional, server default=5000) — Per-probe timeout in milliseconds (0 uses server default)

result = client.ping.once(target_id="your-embedder-id")
print(f"Ping latency: {result.rtt_ms}ms (ok={result.ok})")

Stream ping probe results

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

• target_id (str, format: uuid) — Target resource ID (UUID)
• count (int, format: int32, optional, server default=4) — Number of probes to run (0 uses server default)
• interval_ms (int, format: int32, optional, server default=1000) — Delay between probes in milliseconds (0 uses server default)
• jitter (bool, optional) — Add jitter to probe scheduling
• labels (dict[str, str], optional) — Optional labels to attach to the ping session
• max_in_flight (int, format: int32, optional, server default=1) — Maximum concurrent probes (defaults to 1)
• payload (str, optional) — Explicit UTF-8 payload to send with each probe (mutually exclusive with payload_size_bytes)
• payload_size_bytes (int, format: int32, optional) — Synthetic payload size in bytes (mutually exclusive with payload)
• payload_type (PingPayloadType, optional) — Desired payload type (defaults to provider-specific value)
• stream (bool, optional, SDK default=True) — If True (default), returns a PingStream context manager that yields events as they arrive from the server. If False, collects all events and returns a plain list[PingEvent].
• target_type_hint (PingTargetType, optional) — Optional hint for the target resource type
• timeout_ms (int, format: int32, optional, server default=5000) — Per-probe timeout in milliseconds (0 uses server default)

with client.ping.stream(target_id="your-embedder-id", count=2) as events:
    for event in events:
        print(event)

Async usage: client.ping exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

PingTargetType

String enum: "TARGET_TYPE_UNSPECIFIED" · "EMBEDDER" · "RERANKER" · "LLM"

PingPayloadType

String enum: "PAYLOAD_TYPE_UNSPECIFIED" · "TEXT" · "JSON" · "BINARY"

PingResult

Result from an individual ping probe

• endpoint (PingEndpointInfo) — Resolved endpoint metadata for the target
• seq (int) — Sequential probe number (1-based)
• bytes_sent (int) — Payload bytes transmitted
• bytes_received (int) — Payload bytes received
• ok (bool) — True when the provider responded successfully within the timeout
• http_status (int) — Provider HTTP status code or equivalent transport status
• error_message (str, optional) — Human-readable error message when ok=false
• rtt_ms (float) — Observed round-trip latency in milliseconds
• timing (PingTiming) — Raw timing data recorded on the server
• metadata (dict[str, str], optional) — Additional provider metadata (request IDs, throttling signals, etc.)

PingEndpointInfo

Resolved endpoint metadata for ping responses

• target_type (PingTargetType) — Resolved resource type
• target_id (str) — Target resource ID (UUID)
• resolved_endpoint (str) — Fully resolved endpoint URL used for the probe
• provider (str) — Provider name backing the resource
• model_identifier (str) — Provider-specific model identifier

PingTiming

Timing information captured during a ping probe

• client_send_time_unix_nanos (int) — Client send time (Unix epoch nanoseconds)
• server_received_time_unix_nanos (int) — Server received time (Unix epoch nanoseconds)
• server_send_time_unix_nanos (int) — Server send time (Unix epoch nanoseconds)
• client_receive_time_unix_nanos (int) — Client receive time (Unix epoch nanoseconds)

PingEvent

Streaming event from a ping session

• result (PingResult, optional) — Probe result event
• summary (PingSummary, optional) — Summary emitted at session completion
• notice (PingNotice, optional) — Non-fatal notice emitted during session

PingSummary

Summary emitted at the end of a ping session

• endpoint (PingEndpointInfo) — Endpoint metadata copied from the final probe
• requests (int) — Total number of probes scheduled
• responses (int) — Number of responses received (including timeouts/errors)
• ok (int) — Count of probes that succeeded
• timeouts (int) — Count of probes that exceeded the timeout
• errors (int) — Count of probes that failed for other reasons
• rtt_min_ms (float) — Minimum observed round-trip latency (ms)
• rtt_avg_ms (float) — Average observed round-trip latency (ms)
• rtt_p50_ms (float) — Median (p50) round-trip latency (ms)
• rtt_p90_ms (float) — 90th percentile round-trip latency (ms)
• rtt_p99_ms (float) — 99th percentile round-trip latency (ms)
• rtt_max_ms (float) — Maximum observed round-trip latency (ms)
• requests_per_second (float) — Effective request throughput across the session
• bytes_per_second (float) — Aggregate bytes per second (send + receive)
• applied_limits (dict[str, str], optional) — Resource limits applied by the server

PingNotice

Non-fatal notice emitted during a ping session

• code (str) — Machine-readable notice identifier
• message (str) — Human-readable notice message
• details (dict[str, str], optional) — Additional contextual details