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
• Set partition columns: PATCH https://api.telemetry.sh/tables/<table>/partition-columns
• Delete table: DELETE https://api.telemetry.sh/tables/<table>

Headers

Scope rules:

• GET /tables and GET /tables/<table>/schema require read, write, or read-and-write
• PATCH /tables/<table>/retention, PATCH /tables/<table>/partition-columns, 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:

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

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
  }'

Set partition columns

PATCH https://api.telemetry.sh/tables/<table>/partition-columns

Partition columns organize a table's parts so equality filters can skip unrelated data before a query reads it. The order matters: put the field used by the most queries first. See Choosing partition columns for selection advice and query examples.

The table must already have a schema. You can use top-level or nested scalar fields, such as account_id or request.region. String, boolean, and numeric fields are supported.

Body

The request is rejected if a field does not exist in the current schema, has an unsupported type, is duplicated, is empty, or contains an empty nested-path segment.

Changing the columns creates a new partition specification. New ingested data uses it immediately, while existing parts are rewritten in the background. Queries remain complete during that transition, but the full performance benefit arrives as the rewrite progresses.

Successful requests return 200 OK with the effective settings:

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": ["account_id", "event"],
  "partition_spec_version": 2
}

Example

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

Disable partitioning

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": 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"

Related endpoint

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
• 400 Bad Request if a partition column is invalid or is not a supported field in the current schema
• 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