API Reference

Telemetry

Ingest SDK telemetry from your application runtime. Uses sdk_key body authentication instead of Bearer token.

POST/v1/events

SDK key in body

Ingest SDK telemetry

Accepts telemetry events using an SDK Key in the sdk_key body field. This endpoint does not use the Authorization header.

Supports single-event ({sdk_key, event}) and batch ({sdk_key, batch}) formats. Each event describes a recorded outbound HTTP request, including its hostname, status code and duration. These measurements can help you compare application behavior with vendor reports.

Rate limited per SDK key (1,000 events/minute) and per IP (100 requests/minute). When rate limited, the response includes Retry-After and X-RateLimit-* headers.

Request BodyRequired

sdk_keystringRequired

SDK key from your CheckUpstream dashboard. Used for authentication and rate limiting.

eventTelemetryEventOptional

batchTelemetryEvent[]Optional

Array of telemetry events (max 500)

Responses

okbooleanRequired

Always true on 200 responses

acceptedintegerRequired

Number of events successfully ingested

droppedintegerRequired

Number of events dropped (unknown service, capacity)

sampleRatenumberOptional

Recommended sample rate (0.0-1.0) when approaching rate limits

flushIntervalMsintegerOptional

Recommended flush interval adjustment

disabledbooleanOptional

If true, SDK should stop sending events

resolvedServicesstring[]Optional

Service slugs that were recognized

unknownServicesstring[]Optional

Service slugs that could not be resolved

dropReasonsstring[]Optional

Reasons events were dropped (unknown_service, service_cap, etc.)

Example Response

JSON

{
  "ok": true,
  "accepted": 2,
  "dropped": 0,
  "sampleRate": null,
  "flushIntervalMs": null,
  "disabled": false,
  "resolvedServices": [
    "stripe",
    "openai"
  ],
  "unknownServices": [],
  "dropReasons": []
}

413Payload too large (max 512 KB)

Code Samples

Code

curl -X POST https://ingest.checkupstream.com/v1/events \
  -H 'Content-Type: application/json' \
  -d '{
    "sdk_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "batch": [{
      "service": "api.stripe.com",
      "endpoint": "/v1/charges",
      "method": "POST",
      "status": 200,
      "latency_ms": 342,
      "ts": 1710230400
    }]
  }'

Create a project SDK key

Send telemetry with a project SDK key. A secret API token cannot authenticate these events.

Manage SDK keys Credential guide