Monitoring and alerts

Port usage

Returns traffic samples and the ninety-fifth percentile for a billing period, which is the figure your invoice is calculated from. Samples are five-minute averages.

GET /v1/ports/prt_8f2c1a94/usage?period=YYYY-MM&granularity=5m

{
  "data": {
    "port_id": "prt_8f2c1a94",
    "period": "YYYY-MM",
    "commit_mbps": 2000,
    "percentile_95_in_mbps": 1840,
    "percentile_95_out_mbps": 2310,
    "billable_mbps": 2310,
    "burst_mbps": 310,
    "samples": [
      { "ts": "YYYY-MM-DDTHH:MM:SSZ", "in_mbps": 1502, "out_mbps": 1870 }
    ]
  }
}

billable_mbps is the higher of inbound and outbound at the ninety-fifth percentile, consistent with clause 6 of the master service agreement. Samples for the current period are provisional until the period closes.

Metrics

Time-series telemetry for nodes and circuits. Prefer short windows; this endpoint shares the tighter rate limit with usage (20 requests per minute).

GET /v1/metrics?resource_type=node&resource_id=nod_a1c3e902&from=YYYY-MM-DDTHH:MM:SSZ&to=YYYY-MM-DDTHH:MM:SSZ&granularity=1m

{
  "data": {
    "resource_type": "node",
    "resource_id": "nod_a1c3e902",
    "granularity": "1m",
    "series": [
      {
        "metric": "gpu_utilization_pct",
        "points": [
          { "ts": "YYYY-MM-DDTHH:MM:SSZ", "value": 87.2 }
        ]
      },
      {
        "metric": "gpu_temp_c",
        "points": [
          { "ts": "YYYY-MM-DDTHH:MM:SSZ", "value": 72.0 }
        ]
      },
      {
        "metric": "fabric_errors",
        "points": [
          { "ts": "YYYY-MM-DDTHH:MM:SSZ", "value": 0 }
        ]
      }
    ]
  }
}

For circuits, use resource_type=circuit and metrics such as in_mbps / out_mbps. For ports, prefer the dedicated usage endpoint when you need billing percentiles.

Alert rules

Define threshold rules that evaluate against metrics. Notifications go to the channels you configure (email and/or a webhook URL).

GET /v1/alert-rules
POST /v1/alert-rules
DELETE /v1/alert-rules/{id}

POST /v1/alert-rules
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "name": "GPU hot on train-a-03",
  "resource_type": "node",
  "resource_id": "nod_a1c3e902",
  "metric": "gpu_temp_c",
  "operator": "gt",
  "threshold": 85,
  "duration_seconds": 300,
  "severity": "warning",
  "channels": [
    { "type": "email", "target": "[email protected]" },
    { "type": "webhook", "target": "https://hooks.example.com/sih" }
  ]
}

{
  "data": {
    "id": "arl_9c2e1f40",
    "name": "GPU hot on train-a-03",
    "state": "active",
    "severity": "warning",
    "created_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

operator is one of gt, gte, lt, lte. severity is info, warning, or critical. The condition must hold for duration_seconds before an alert fires.

Firing alerts

GET /v1/alerts?state=firing

{
  "data": [
    {
      "id": "alt_5e8a1c92",
      "rule_id": "arl_9c2e1f40",
      "state": "firing",
      "severity": "warning",
      "message": "gpu_temp_c gt 85 for 300s on nod_a1c3e902",
      "fired_at": "YYYY-MM-DDTHH:MM:SSZ",
      "resolved_at": null
    }
  ]
}

state is firing or resolved. Deduplicate on id when consuming webhooks; the same alert may be delivered more than once.

Webhook events

{
  "event": "alert.triggered",
  "id": "evt_c4d8e901",
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "data": {
    "alert_id": "alt_5e8a1c92",
    "rule_id": "arl_9c2e1f40",
    "severity": "warning",
    "message": "gpu_temp_c gt 85 for 300s on nod_a1c3e902"
  }
}

• alert.triggered — rule condition met for the configured duration
• alert.resolved — condition cleared
• usage.period_closed — billing period usage finalized

Channel webhooks you configure on a rule use the same HMAC X-SIH-Signature scheme as account webhooks. See the overview.