> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Track and query custom telemetry events from agents, CLI tools, and external runners.

# Telemetry API

The Telemetry API is a general-purpose event bus for emitting structured events from agents, CLI scripts, and external compute runners. Use it to track custom metrics (experiment convergence, loss curves, throughput), system diagnostics (GPU utilization samples), or arbitrary timestamped facts you want queryable later.

## List Events

<ParamField query="labId" type="string" required>
  Convex ID of the lab.
</ParamField>

<ParamField query="event" type="string">
  Filter to a specific event name (e.g., `gpu.utilization`, `loss.epoch`).
</ParamField>

<ParamField query="limit" type="number" default={100}>
  Max events to return. Capped at 500.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  # All events
  curl "https://www.hubify.com/api/v1/telemetry?labId=$LAB_ID&limit=50" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"

  # Filter to GPU utilization samples
  curl "https://www.hubify.com/api/v1/telemetry?labId=$LAB_ID&event=gpu.utilization" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```
</CodeGroup>

<ResponseField name="events" type="object[]" required>
  Telemetry events, newest first.

  <Expandable title="Event">
    <ResponseField name="_id" type="string" required>Convex document ID.</ResponseField>
    <ResponseField name="event" type="string" required>Event name (dot-separated, e.g., `loss.epoch`, `experiment.step`).</ResponseField>
    <ResponseField name="value" type="number">Numeric metric value, if applicable.</ResponseField>
    <ResponseField name="payload" type="string">JSON-encoded extra context.</ResponseField>
    <ResponseField name="agentId" type="string">Emitting agent, if any.</ResponseField>
    <ResponseField name="experimentId" type="string">Linked experiment, if any.</ResponseField>
    <ResponseField name="createdAt" type="number">Unix ms.</ResponseField>
  </Expandable>
</ResponseField>

## Track Event

<ParamField body="labId" type="string" required>Convex lab ID.</ParamField>
<ParamField body="event" type="string" required>Event name (dot-separated, max 100 chars).</ParamField>
<ParamField body="value" type="number">Numeric metric value.</ParamField>
<ParamField body="payload" type="string">JSON-encoded extra context (max 2KB).</ParamField>
<ParamField body="agentId" type="string">Convex agent ID emitting the event.</ParamField>
<ParamField body="experimentId" type="string">Convex experiment ID to link.</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  # Report GPU utilization from a RunPod worker
  curl -X POST https://www.hubify.com/api/v1/telemetry \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "labId": "$LAB_ID",
      "event": "gpu.utilization",
      "value": 94.2,
      "payload": "{\"podId\":\"abc123\",\"gpuType\":\"H200 SXM\"}"
    }'
  ```

  ```python Python (in a RunPod worker) theme={null}
  import requests, json, os

  requests.post(
    "https://www.hubify.com/api/v1/telemetry",
    headers={"Authorization": f"Bearer {os.environ['HUBIFY_TOKEN']}"},
    json={
      "labId": os.environ["HUBIFY_LAB_ID"],
      "event": "loss.epoch",
      "value": loss,
      "experimentId": exp_id,
    }
  )
  ```
</CodeGroup>

<ResponseField name="id" type="string" required>New telemetry event Convex ID.</ResponseField>