API Reference

The zymtrace REST API gives you programmatic access to call-path data, agent management, alert configuration, and metric exports. Base URL: https://api.gozymtrace.com/v1

Authentication

All API requests require a bearer token. Generate tokens in your dashboard under Settings > API Tokens.

bash 
curl https://api.gozymtrace.com/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN"

Agents

GET /agents

Returns a list of all connected agents for your organization.

Response 200 
{
  "agents": [
    {
      "id": "agt_01hwx5b3k4q2z",
      "hostname": "gpu-node-04",
      "pid": 18342,
      "process_name": "python inference_server.py",
      "status": "active",
      "gpu_count": 4,
      "connected_at": "2026-06-15T09:14:22Z",
      "last_batch_at": "2026-06-15T12:01:07Z"
    }
  ]
}

GET /agents/:id

Returns a single agent with hardware details.

DELETE /agents/:id

Detaches and removes an agent. The agent process continues running on the host but stops streaming data.

Flamegraphs

GET /flamegraphs

Returns aggregated call-path data in the Brendan Gregg folded stacks format, suitable for rendering with d3-flame-graph or similar libraries.

Query parameters 
agent_id   string   required   Agent ID to query
from       ISO8601  required   Start time (e.g. 2026-06-15T11:00:00Z)
to         ISO8601  required   End time (e.g. 2026-06-15T12:00:00Z)
format     string   optional   "folded" (default) | "json"
min_us     int      optional   Minimum kernel duration filter (microseconds)
Response 200 (format=folded) 
model_forward;attention;F.scaled_dot_product_attention;cudnn_flash_attn 8420
model_forward;attention;F.scaled_dot_product_attention;volta_fp16_s884gemm 3180
model_forward;mlp;F.linear;cublas_gemm_batched 2240
model_forward;mlp;F.gelu;elementwise_kernel 540

Metrics

GET /metrics

Returns time-series GPU utilization and kernel dispatch frequency data in JSON. Compatible with Prometheus remote-write format via the format=prometheus parameter.

Query parameters 
agent_id   string   required
metric     string   required   "gpu_util" | "mem_bw" | "kernel_hz" | "sm_occupancy"
from       ISO8601  required
to         ISO8601  required
step       string   optional   Resolution: "10s" (default) | "1m" | "5m"

Alerts

POST /alerts

Create an alert rule. zymtrace will send a webhook when the condition is met.

Request body 
{
  "name": "attention kernel p99 spike",
  "agent_id": "agt_01hwx5b3k4q2z",
  "condition": {
    "call_path_pattern": "*attention*",
    "metric": "kernel_duration_p99_us",
    "operator": "gt",
    "threshold": 4000
  },
  "webhook_url": "https://hooks.slack.com/services/..."
}

Rate limits

Plan Requests / minute Flamegraph window max
Trace 60 7 days
Growth 600 30 days
Scale 2400 90 days

Error codes

HTTP status Error code Meaning
401 unauthorized Missing or invalid API token
403 forbidden Token valid but plan does not support this endpoint
404 not_found Agent ID does not exist in this organization
429 rate_limited Too many requests. Retry after the value in the Retry-After header
422 validation_error Request body failed validation. Check the errors field in the response