SDK Reference

CheckUpstream SDKs instrument your application to capture outbound HTTP telemetry. They automatically detect calls to supported services and report latency, status codes, and error rates. SDKs are available for 8 languages, all sharing the same configuration surface.

Installation

npm install @checkupstream/sdk

Initialization

The @checkupstream/sdk package patches globalThis.fetch to automatically intercept outbound HTTP calls.

import { checkupstream } from "@checkupstream/sdk";

checkupstream.init({
  apiKey: "cup_your_api_key",
});

// Your existing fetch calls are now instrumented
const response = await fetch("https://api.stripe.com/v1/charges");
// → Telemetry event: { host: "api.stripe.com", endpoint: "/v1/charges", status: 200, latency_ms: 142 }

Shutdown

process.on("SIGTERM", async () => {
  await checkupstream.shutdown();
  process.exit(0);
});

Framework integrations: Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit

Common Configuration

All SDKs share the same configuration options. Field names use the idiomatic casing for each language (e.g., apiKey in JS, api_key in Python, APIKey in Go).

CheckUpstreamConfig

Property	Type	Status	Default	Description
`apiKey`	`string`	Required	—	Your project API key (starts with cup_)
`endpoint`	`string`	Optional	`"https://ingest.checkupstream.com/v1/events"`	Telemetry ingestion endpoint
`services`	`string[]`	Optional	`undefined`	Restrict monitoring to specific service slugs. If omitted, all auto-detected services are tracked.
`flushIntervalMs`	`number`	Optional	`10000`	How often to flush the telemetry batch (milliseconds)
`maxBatchSize`	`number`	Optional	`100`	Maximum events per batch before auto-flush
`enabled`	`boolean`	Optional	`true`	Set to false to disable the SDK entirely (useful for test environments)

Telemetry Events

Each intercepted request generates a telemetry event:

TelemetryEvent

Property	Type	Status	Default	Description
`host`	`string`	Required	—	Request hostname, e.g. "api.stripe.com". The server maps hosts to services.
`endpoint`	`string`	Required	—	Request path, e.g. "/v1/charges"
`status`	`number`	Required	—	HTTP status code
`latency_ms`	`number`	Required	—	Request duration in milliseconds
`ts`	`number`	Required	—	Unix timestamp (ms)

Events are batched and sent as a TelemetryBatch:

TelemetryBatch

Property	Type	Status	Default	Description
`sdk_key`	`string`	Required	—	Your API key
`batch`	`TelemetryEvent[]`	Required	—	Array of telemetry events

Auto-Detected Services

All SDKs automatically recognize outbound requests to these domains:

Domain	Service
`api.stripe.com`	Stripe
`api.openai.com`	OpenAI
`api.anthropic.com`	Anthropic
`s3.amazonaws.com`	AWS S3
`dynamodb.amazonaws.com`	AWS DynamoDB
`api.twilio.com`	Twilio
`api.sendgrid.com`	SendGrid
`api.resend.com`	Resend
`api.clerk.com`	Clerk
`api.supabase.co`	Supabase
`api.posthog.com`	PostHog
`api.segment.io`	Segment
`api.mixpanel.com`	Mixpanel
`api.algolia.com`	Algolia
`api.cloudinary.com`	Cloudinary

Subdomain matching is also supported: for example, us-east-1.s3.amazonaws.com matches AWS S3.

Filtering Services

To only track specific services, pass a services array:

checkupstream.init({
  apiKey: "cup_your_api_key",
  services: ["stripe", "openai"],
});

Requests to other services will be passed through without instrumentation.

Disabling in Tests

checkupstream.init({
  apiKey: "cup_test_key",
  enabled: process.env.NODE_ENV === "production",
});