Telemetry
Browse docs
Discussion TopicsUpdated 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. Set retention by table
  2. Delete rows or a table
  3. Design for deletability
  4. Verify the lifecycle

Data Retention and Deletion

Retention is part of an event contract. Decide how long a table remains useful, which identifiers it contains, and whether legal or customer commitments require a shorter lifecycle before sending production data.

Set retention by table

Tables with different purposes should not inherit one accidental policy. High-volume operational events may need a shorter window than low-volume billing milestones or audit records.

Use the Tables API to set or clear a retention period:

curl -X PATCH https://api.telemetry.sh/tables/api_requests/retention \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "retention_days": 30 }'

The Tables API reference documents the current request and response contract.

Delete rows or a table

Selective deletion rewrites affected stored data asynchronously. Whole-table deletion removes the table from normal use while cleanup proceeds. Because deletion is destructive, resolve the exact table and predicate with a read-only query first.

SELECT COUNT(*) AS rows_to_delete
FROM product_events
WHERE account_id = 'account_123';

Then use the supported deletion endpoint described in the Delete API reference. Keep the target table, predicate, requester, approval, and completion evidence in the system responsible for the deletion request. Do not copy private row contents into that record.

Design for deletability

Use stable opaque account and user identifiers when a table must support subject-level deletion. Free-form text and inconsistent identifiers make it difficult to find every applicable row safely.

Avoid sending secrets, payment data, request bodies, or raw prompts in the first place. Deletion is not a substitute for data minimization.

Verify the lifecycle

After changing retention, fetch table metadata and confirm the stored policy. After deletion, query the exact predicate until the operation is complete. Validate dashboards and saved queries that expected the removed history.

Review retention when a new identifier, event source, region, or customer commitment is introduced. Continue with redacting sensitive data and partition columns.