Telemetry API

API reference for querying and ingesting telemetry data

The Telemetry API allows you to query errors, metrics, and traces collected by Cased. All endpoints require authentication with an API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Projects

List Projects

Returns all telemetry projects for your organization.

GET /api/v1/telemetry/projects/

Example Request

curl -X GET https://app.cased.com/api/v1/telemetry/projects/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "projects": [
    {
      "id": "2qNyVcXdPmE8K4L6R9T1W3Y5",
      "name": "production-api",
      "dsn": "https://abc123@telemetry.cased.com/1",
      "is_active": true,
      "created_at": "2025-01-10T10:00:00Z"
    }
  ]
}

Create Project

Creates a new telemetry project and returns a DSN for the Sentry SDK.

POST /api/v1/telemetry/projects/

Body

Field	Type	Description
`name`	string	Required. Project name (e.g., “production-api”)

Example Request

curl -X POST https://app.cased.com/api/v1/telemetry/projects/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-service"}'

Example Response

{
  "id": "2qNyVcXdPmE8K4L6R9T1W3Y5",
  "name": "my-service",
  "dsn": "https://abc123def456@telemetry.cased.com/1",
  "is_active": true,
  "created_at": "2025-01-10T10:00:00Z"
}

Query Errors

List Errors

Returns error events with optional filtering.

GET /api/v1/telemetry/query/errors/

Query Parameters

Parameter	Type	Default	Description
`since`	string	`24h`	Time range: `1h`, `6h`, `24h`, `7d`, `30d`
`project_id`	string	-	Filter by telemetry project
`level`	string	-	Filter by level: `error`, `warning`, `info`
`search`	string	-	Search in error message
`limit`	integer	100	Max results (1-1000)
`offset`	integer	0	Pagination offset

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/errors/?since=24h&level=error&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "events": [
    {
      "event_id": "abc123",
      "timestamp": "2025-01-10T15:30:00Z",
      "level": "error",
      "message": "Connection timeout",
      "exception_type": "TimeoutError",
      "exception_value": "Connection to database timed out after 30s",
      "platform": "python",
      "sdk_name": "sentry.python",
      "tags": {
        "environment": "production",
        "service": "api"
      },
      "stack_trace": "Traceback (most recent call last):\n  File \"app.py\", line 42..."
    }
  ],
  "total": 156,
  "has_more": true
}

Query Metrics

Get Container Metrics

Returns container metrics from cased-agent.

GET /api/v1/telemetry/query/metrics/

Query Parameters

Parameter	Type	Default	Description
`since`	string	`1h`	Time range: `5m`, `15m`, `1h`, `6h`, `24h`
`cluster`	string	-	Filter by cluster ID
`namespace`	string	-	Filter by Kubernetes namespace
`pod`	string	-	Filter by pod name (prefix match)
`container`	string	-	Filter by container name
`metric`	string	-	Filter by metric name

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/metrics/?since=1h&namespace=production&metric=cpu_usage_cores" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "metrics": [
    {
      "timestamp": "2025-01-10T15:30:00Z",
      "cluster": "prod",
      "namespace": "production",
      "pod": "api-server-abc123",
      "container": "api",
      "metric_name": "cpu_usage_cores",
      "value": 0.45
    }
  ],
  "total": 1250
}

Query Traces

List Traces

Returns distributed traces and spans.

GET /api/v1/telemetry/query/traces/

Query Parameters

Parameter	Type	Default	Description
`since`	string	`1h`	Time range
`project_id`	string	-	Filter by telemetry project
`service`	string	-	Filter by service name
`operation`	string	-	Filter by operation name
`min_duration_ms`	integer	-	Filter by minimum duration
`limit`	integer	100	Max results

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/traces/?since=1h&service=api&min_duration_ms=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "traces": [
    {
      "trace_id": "abc123def456",
      "root_span": {
        "span_id": "span123",
        "service": "api",
        "operation": "POST /users",
        "duration_ms": 1250,
        "status": "ok",
        "timestamp": "2025-01-10T15:30:00Z"
      },
      "span_count": 5,
      "services": ["api", "database", "cache"]
    }
  ],
  "total": 42
}

Query Stats

Get Telemetry Statistics

Returns aggregate statistics for telemetry data.

GET /api/v1/telemetry/query/stats/

Query Parameters

Parameter	Type	Default	Description
`since`	string	`24h`	Time range
`project_id`	string	-	Filter by project

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/stats/?since=24h" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "stats": {
    "events": {
      "total": 15234,
      "errors": 342,
      "warnings": 1205,
      "info": 13687
    },
    "metrics": {
      "total": 125000,
      "containers": 45,
      "pods": 23
    },
    "traces": {
      "total": 8500,
      "avg_duration_ms": 145
    }
  },
  "period": {
    "start": "2025-01-09T15:30:00Z",
    "end": "2025-01-10T15:30:00Z"
  }
}

Ingestion Endpoints

These endpoints are typically used by SDKs, not called directly.

Ingest Errors (Sentry SDK)

POST /api/<project_id>/envelope/

Used by the Sentry SDK. Configure your DSN and the SDK handles this automatically.

Ingest Metrics (cased-agent)

POST /api/v1/telemetry/metrics

Used by cased-agent to send container metrics.

Headers

Header	Description
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Body

{
  "metrics": [
    {
      "timestamp": "2025-01-10T15:30:00Z",
      "cluster": "prod",
      "namespace": "production",
      "pod": "api-server-abc123",
      "container": "api",
      "node": "ip-10-0-1-100",
      "metrics": {
        "cpu_usage_cores": 0.45,
        "memory_usage_bytes": 536870912,
        "network_rx_bytes": 1048576,
        "network_tx_bytes": 524288
      }
    }
  ]
}

Ingest Spans

POST /api/v1/telemetry/spans

Used to ingest distributed tracing spans.

Body

{
  "spans": [
    {
      "trace_id": "abc123def456",
      "span_id": "span123",
      "parent_span_id": null,
      "service": "api",
      "operation": "POST /users",
      "start_time": "2025-01-10T15:30:00Z",
      "duration_ms": 125,
      "status": "ok",
      "attributes": {
        "http.method": "POST",
        "http.url": "/users"
      }
    }
  ]
}

Cluster Aggregation

These endpoints provide cluster-wide views of your infrastructure, aggregating metrics across all nodes and pods.

Get Cluster Overview

Returns a high-level summary of cluster health including CPU, memory, pod counts, and active issues.

GET /api/v1/telemetry/query/cluster/overview/

Query Parameters

Parameter	Type	Default	Description
`hours_back`	integer	`1`	Hours to look back (1-24)

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/cluster/overview/?hours_back=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "hours_back": 1,
  "cluster": {
    "node_count": 5,
    "total_pods": 42,
    "cpu_used_percent": 35.2,
    "memory_used_percent": 58.4,
    "memory_total_gb": 80.0,
    "memory_used_gb": 46.7
  },
  "nodes": {
    "ip-10-0-1-100": {
      "cpu_used_percent": 42.1,
      "memory_used_percent": 65.3
    }
  },
  "pods_by_namespace": {
    "production": 25,
    "staging": 12,
    "kube-system": 5
  },
  "issues": {
    "crashloops": 0,
    "warnings": 3,
    "total": 3
  },
  "http": {
    "error_rate": 0.5,
    "latency_p95": 145.2,
    "request_count": 15234
  }
}

Get Node Comparison

Compares metrics across all nodes to identify imbalances or hot spots.

GET /api/v1/telemetry/query/cluster/nodes/

Query Parameters

Parameter	Type	Default	Description
`hours_back`	integer	`1`	Hours to look back (1-24)

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/cluster/nodes/?hours_back=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "hours_back": 1,
  "node_count": 5,
  "nodes": {
    "ip-10-0-1-100": {
      "cpu_used_percent": {"avg": 42.1, "min": 30.5, "max": 65.2},
      "memory_used_percent": {"avg": 65.3, "min": 60.1, "max": 72.0},
      "memory_total_gb": 16.0,
      "pod_count": 12
    }
  },
  "rankings": {
    "by_cpu_usage": ["ip-10-0-1-100", "ip-10-0-1-101", "ip-10-0-1-102"],
    "by_memory_usage": ["ip-10-0-1-101", "ip-10-0-1-100", "ip-10-0-1-102"]
  },
  "hottest_node": "ip-10-0-1-100"
}

Get Top Resource Consumers

Identifies the pods consuming the most CPU or memory across the cluster.

GET /api/v1/telemetry/query/cluster/top/

Query Parameters

Parameter	Type	Default	Description
`resource`	string	`cpu`	Resource type: `cpu` or `memory`
`hours_back`	integer	`1`	Hours to look back (1-24)
`limit`	integer	`10`	Number of results (1-50)

Example Request

curl -X GET "https://app.cased.com/api/v1/telemetry/query/cluster/top/?resource=cpu&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "resource": "cpu",
  "hours_back": 1,
  "limit": 5,
  "top_consumers": [
    {
      "namespace": "production",
      "pod": "api-server-abc123",
      "avg_percent": 85.2,
      "max_percent": 98.1
    },
    {
      "namespace": "production",
      "pod": "worker-xyz789",
      "avg_percent": 72.1,
      "max_percent": 89.5
    }
  ],
  "by_namespace": {
    "production": {"avg": 45.2, "pod_count": 25},
    "staging": {"avg": 22.1, "pod_count": 12}
  }
}

Rate Limits

Endpoint	Limit
Query endpoints	100 requests/minute
Ingestion endpoints	1000 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: Request limit
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset timestamp