Telemetry

Ingest telemetry events from SDKs and OpenTelemetry collectors.

Telemetry

The telemetry endpoint receives structured event data from Checkrd SDKs and OpenTelemetry collectors. Events are batched, validated, and written to the telemetry pipeline.

Ingest Events

POST /v1/telemetry

Auth: API Key

Parameter	Type	Required	Description
`events`	array	Yes	1 to 1,000 telemetry events.
`sdk_version`	string	No	SDK version identifier.

Each event in the events array:

Field	Type	Required	Description
`agent_id`	UUID	Yes	The agent that generated this event.
`timestamp`	ISO 8601	Yes	When the request was made.
`request_id`	string	Yes	Unique correlation ID.
`method`	string	Yes	HTTP method (GET, POST, etc.).
`url_host`	string	Yes	Target API host (e.g., `api.stripe.com`).
`url_path`	string	Yes	Parameterized URL path (identifiers replaced with `{id}`).
`status_code`	integer	Yes	HTTP response status code.
`latency_ms`	integer	No	Request duration in milliseconds.
`policy_result`	string	Yes	`allowed`, `denied`, or `error`.
`deny_reason`	string	No	Rule name that caused denial (e.g., `block-deletes`).

bash

curl -X POST https://api.checkrd.io/v1/telemetry \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "agent_id": "01916a3e-7b2c-...",
        "timestamp": "2026-04-12T09:15:00Z",
        "request_id": "req_abc123",
        "method": "GET",
        "url_host": "api.salesforce.com",
        "url_path": "/services/data/v58.0/sobjects/Contact/{id}",
        "status_code": 200,
        "latency_ms": 142,
        "policy_result": "allowed"
      }
    ]
  }'

Response 200 OK

json

{ "accepted": 1 }

Ed25519 Signatures

SDKs can sign telemetry batches with Ed25519 for non-repudiation. Include these headers:

Header	Description
`x-checkrd-signature`	Hex-encoded Ed25519 signature.
`x-checkrd-public-key`	Hex-encoded public key (if not yet registered).

Signatures are verified against the agent's registered public key. Both invalid and missing signatures are rejected on the dedicated telemetry-ingestion service.

Rate Limiting

Telemetry ingestion is rate-limited per organization based on plan tier. Rate limit headers are included in every response. When limited, the API returns 429 with a Retry-After header.

OTLP Ingestion

POST /v1/traces

Auth: API Key (via X-API-Key header)

Host: OTLP ingestion runs on the telemetry-ingestion service, not the main API host. Use https://ingest.checkrd.io/v1/traces (or your self-hosted ingestion URL).

Accepts OpenTelemetry Protocol (OTLP) spans in protobuf or JSON format. Agents are auto-provisioned from the service.name resource attribute.

bash

# Point your OTel Collector exporter at Checkrd
exporters:
  otlphttp:
    endpoint: "https://ingest.checkrd.io/v1/traces"
    headers:
      X-API-Key: "ck_live_..."

OTLP spans are translated to Checkrd telemetry events. GenAI semantic conventions (model, system, token counts) are extracted automatically.

Zero code changes

If your agents already emit OpenTelemetry traces, point the collector at Checkrd. No SDK integration required.

Policies Dashboard