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.).
`host`	string	Yes	Target API host (e.g., `api.stripe.com`).
`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 "Authorization: Bearer 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",
        "host": "api.salesforce.com",
        "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. Invalid signatures are rejected. Missing signatures are accepted with a warning (configurable via TELEMETRY_SIGNATURE_MODE).

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 Authorization: Bearer)

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://api.checkrd.io/v1/traces"
    headers:
      Authorization: "Bearer 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