Telemetry

Telemetry API

Submit telemetry data from satellites, ground stations, and data centers.

POST /api/v1/telemetry

Submit a single telemetry data point.

Request

POST /api/v1/telemetry
Authorization: Bearer <token>
Content-Type: application/json

Parameters

Name	Type	Required	Description
timestamp	string	Yes	ISO 8601 timestamp
node_id	string	Yes	Unique node identifier
node_type	string	Yes	satellite, ground_station, or data_center
snr_db	number	No	Signal-to-noise ratio in dB
latency_ms	number	No	Network latency in milliseconds
throughput_gbps	number	No	Data throughput in Gbps
atmospheric_state	object	No	Environmental conditions (key-value pairs)
queue_depth_gb	number	No	Data queue size in GB
utilization	number	No	Resource utilization (0-1)
capacity_gbps	number	No	Maximum capacity in Gbps
source	string	No	Data source identifier
confidence	number	No	Confidence level (0-1, default: 1.0)

Example Request

curl -X POST https://api.constellation-io.com/api/v1/telemetry \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-01-16T20:00:00Z",
    "node_id": "sat-001",
    "node_type": "satellite",
    "snr_db": 25.5,
    "latency_ms": 12.3,
    "throughput_gbps": 45.6,
    "utilization": 0.75,
    "queue_depth_gb": 15.2,
    "capacity_gbps": 100.0
  }'

Response

{
  "success": true,
  "message": "Telemetry data received successfully",
  "telemetry_id": "tel-sat-001-1705434000",
  "received_at": "2026-01-16T20:00:00.123Z"
}

Response Fields

Name	Type	Description
success	boolean	Whether the request succeeded
message	string	Human-readable status message
telemetry_id	string	Unique ID for this telemetry point
received_at	string	Server timestamp when data was received

Node Types

string

Value	Description
satellite	Orbital assets (LEO, MEO, GEO)
ground_station	Ground-based receivers/transmitters
data_center	Terrestrial processing facilities

Error Responses

Validation Error (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "node_type must be one of: satellite, ground_station, data_center",
    "field": "node_type"
  }
}

Processing Error (500)

{
  "success": false,
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Failed to publish telemetry to queue"
  }
}

CLI Example

constellation telemetry post \
  --node sat-001 \
  --type satellite \
  --snr 25.5 \
  --latency 12.3 \
  --throughput 45.6

Or from a JSON file:

constellation telemetry post -f telemetry.json

Python Example

import requests

response = requests.post(
    "https://api.constellation-io.com/api/v1/telemetry",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "timestamp": "2026-01-16T20:00:00Z",
        "node_id": "sat-001",
        "node_type": "satellite",
        "snr_db": 25.5,
        "latency_ms": 12.3,
        "throughput_gbps": 45.6,
    },
)

print(response.json())

Rate Limits

• Single endpoint: 1,000 requests/minute per operator
• Batch endpoint: 100 requests/minute per operator

For higher throughput, use the batch endpoint.