Fleet & Telemetry

Agent telemetry ingestion and fleet-wide metrics. All endpoints require authentication.

These endpoints are primarily used by Embedded-Local deployments where on-premise agents report telemetry back to the Zyntem cloud.

Ingest agent telemetry

POST /v1/agents/{agent_id}/telemetry

Accepts a batch of telemetry data points from an on-premise agent (max 100 per request). Anomaly detection runs asynchronously after ingestion.

Path parameters

Parameter	Type	Description
agent_id	string	Agent identifier (1-255 characters)

Request body

Field	Type	Required	Description
data_points	array	Yes	1-100 telemetry data points

Each data point:

Field	Type	Default	Description
transaction_count_since_last	integer	0	Transactions since last report
transaction_count_total	integer	0	Cumulative transaction count
error_count_since_last	integer	0	Errors since last report
error_rate	number	0	Error rate percentage
avg_response_time_ms	number	0	Average response time in milliseconds
storage_used_bytes	integer	0	Storage used
storage_available_bytes	integer	0	Storage available
uptime_seconds	integer	0	Agent uptime in seconds
adapter_versions	object	{}	Map of country adapter name to version

Example

curl -X POST https://api.zyntem.dev/v1/agents/pos-agent-001/telemetry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_live_abc123def456..." \
  -d '{
    "data_points": [{
      "transaction_count_since_last": 47,
      "transaction_count_total": 12340,
      "error_count_since_last": 2,
      "error_rate": 0.3,
      "avg_response_time_ms": 45.2,
      "storage_used_bytes": 1073741824,
      "storage_available_bytes": 4294967296,
      "uptime_seconds": 86400,
      "adapter_versions": {"spain": "1.2.0", "france": "1.1.0"}
    }]
  }'

Response 202 Accepted

{
  "accepted": 1,
  "timestamp": "2026-03-23T12:00:00Z"
}

---

Get fleet metrics

GET /v1/fleet/metrics?account_id={uuid}&range=24h

Returns aggregated telemetry metrics across all agents for an account.

Query parameters

Parameter	Type	Required	Description
account_id	uuid	Yes	Account ID (must match authenticated account)
range	string	No	Time range: 1h, 6h, 24h (default), 7d, 30d

Example

curl "https://api.zyntem.dev/v1/fleet/metrics?account_id=9f8e7d6c-5b4a-3210-fedc-ba0987654321&range=24h" \
  -H "Authorization: Bearer zyn_live_abc123def456..."

Response 200 OK

{
  "account_id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "range": "24h",
  "metrics": {
    "total_transactions": 5230,
    "total_errors": 12,
    "avg_error_rate": 0.23,
    "total_storage_bytes": 10737418240,
    "agent_count": 8,
    "reporting_agents": 7
  },
  "time_series": []
}