Telemetry
Browse docs
Getting StartedUpdated July 27, 2026Reviewed by the Telemetry product team2 min read

Use this doc with your coding agent

Copy a Telemetry prompt and ask Claude Code, Codex, or Cursor to instrument the workflow covered here.

PromptsGet API key
On this page
  1. Choose the narrowest scope
  2. Send the key
  3. Separate keys by workload
  4. Rotate and revoke safely

API Keys and Authentication

Telemetry API requests use a team API key. Treat the key like a production credential: create it for a named workload, give it the minimum required scope, store it outside source control, and revoke it when the workload is retired.

Open Team Settings → API Keys to create or manage keys. The full value is a credential, so copy it into the target secret manager rather than a shared document or issue.

Choose the narrowest scope

Telemetry supports three scopes:

Scope Use it for
read Queries, table discovery, schemas, and read-only reporting
write Event ingestion and supported write operations
read-and-write A trusted server or automation that must both send and query data

An application that only emits events normally needs write. A reporting job normally needs read. Avoid giving a browser, mobile application, public repository, or user-authored script a team key.

Send the key

HTTP endpoints accept the key as the raw Authorization value or as a bearer token:

curl https://api.telemetry.sh/tables \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

SDK initialization accepts the same API key. Keep initialization in server-side code and use an environment variable or secret-manager lookup:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

Do not use a public build-time prefix such as NEXT_PUBLIC_ or serialize the key into client configuration.

Separate keys by workload

Use distinct keys for production ingestion, staging, scheduled reporting, and coding-agent setup. Workload-specific keys make rotation and incident response smaller: revoking one reporting key should not interrupt event ingestion.

Name the key after its owner and purpose. Record where the key is deployed, its scope, and the expected rotation owner without recording the key value itself.

Rotate and revoke safely

Create a replacement key first, deploy it to the workload, verify successful requests, and then revoke the previous key. Exercise both ingestion and query paths when rotating a read-and-write key.

If a key appears in a commit, log, screenshot, prompt, or public client bundle, treat it as compromised. Revoke it immediately, replace it, and review the affected team tables and query activity.

Continue with the Log API, Query API, and sensitive-data guidance.