Telemetry
Browse docs
API ReferenceUpdated March 27, 2026

Tables

The Tables API lets you inspect and manage tables programmatically.

Supported operations:

  • List tables: GET https://api.telemetry.sh/tables
  • Get schema: GET https://api.telemetry.sh/tables/<table>/schema
  • Set retention: PATCH https://api.telemetry.sh/tables/<table>/retention
  • Delete table: DELETE https://api.telemetry.sh/tables/<table>

Headers

Name Type Description
Content-Type String Use application/json for PATCH.
Authorization String Your API key, either as the raw key or as Bearer <key>.

Scope rules:

  • GET /tables and GET /tables/<table>/schema require read, write, or read-and-write
  • PATCH /tables/<table>/retention and DELETE /tables/<table> require write or read-and-write

Table path contract

The <table> path segment is normalized by the API before forwarding:

  • spaces are converted to underscores
  • letters are lowercased
  • after normalization, only lowercase ASCII letters, numbers, and _ are allowed

Examples:

  • Uber Rides becomes uber_rides
  • graphjson_egress stays graphjson_egress
  • my-table is rejected because - is not allowed

Use canonical table names containing only lowercase letters, numbers, and underscores if you want predictable behavior.

List tables

GET https://api.telemetry.sh/tables

Supported query parameters:

Field Type Required Exact contract Default
page Integer No Positive integer page number. Values less than 1 are rejected. 1
pageSize Integer No Positive integer page size. Values greater than 100 are clamped to 100. The API also accepts the legacy alias page_size. 50

Successful requests return 200 OK:

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "tables": [
    "heartbeat",
    "telemetry_user_events",
    "graphjson_egress"
  ]
}

Example

curl "https://api.telemetry.sh/tables?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

Get table schema

GET https://api.telemetry.sh/tables/<table>/schema

This returns:

  • the parsed schema object for the table
  • the current retention policy, if any
  • partition metadata, if any

Successful requests return 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "schema": {
    "fields": [
      {
        "name": "timestamp_utc",
        "data_type": {
          "Timestamp": ["Millisecond", "UTC"]
        },
        "nullable": true,
        "dict_id": 0,
        "dict_is_ordered": false,
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "retention_days": null,
  "partition_columns": null,
  "partition_spec_version": null
}

Example

curl https://api.telemetry.sh/tables/graphjson_egress/schema \
  -H "Authorization: $API_KEY"

Set table retention

PATCH https://api.telemetry.sh/tables/<table>/retention

Body

Field Type Required Exact contract Example
retentionDays Integer or null No Positive integer number of days to retain data. Use null to clear retention and keep data indefinitely. The API also accepts the legacy alias retention_days. 30

Notes:

  • Values less than 1 are rejected.
  • If you send {} or {"retentionDays": null}, retention is cleared.

Successful requests return 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": null,
  "partition_spec_version": null
}

Example

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": 30
  }'

Clear retention

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": null
  }'

Delete table

DELETE https://api.telemetry.sh/tables/<table>

This permanently deletes the table and all of its data.

Successful requests return 200 OK:

{
  "status": "success",
  "deleted_table": {
    "name": "graphjson_egress"
  }
}

Example

curl -X DELETE https://api.telemetry.sh/tables/graphjson_egress \
  -H "Authorization: $API_KEY"

Telemetry also still supports the legacy DELETE /delete endpoint for deleting rows with a where clause. Use the Tables API when you want whole-table lifecycle operations.

Common errors

  • 400 Bad Request if the table name contains invalid characters after normalization
  • 400 Bad Request if retentionDays is not a positive integer or null
  • 403 Forbidden if the API key does not have permission for the requested operation
  • 401 Unauthorized if the API key is missing or invalid
  • 404 Not Found if the table does not exist