Delete

The Delete API allows you to remove data from Telemetry. You can delete specific rows based on a condition or remove an entire table. Be cautious when using this API, as deleting data is irreversible.

DELETE https://api.telemetry.sh/delete

Headers

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

Scope rules:

DELETE /delete requires write or read-and-write

Body

Name	Type	Description
table	String	The table you want to delete data from
where	String (optional)	SQL clause for what rows to delete

If where is omitted, Telemetry treats the request as a whole-table delete.

Success responses

Delete responses are asynchronous cleanup acknowledgements. The API returns 200 OK as soon as the delete rewrite or table-disable step has been scheduled successfully.

Delete matching rows

{
  "status": "success",
  "message": "Delete rewrite completed; part cleanup is asynchronous"
}

Delete an entire table

{
  "status": "success",
  "message": "Table disabled; part cleanup is asynchronous"
}

Example usage with cURL

To delete all rows older than 3 days from the table named uber_rides using cURL, you can use the following command:

API_KEY="YOUR_API_KEY"
WHERE_CONDITION="timestamp <= (now() - INTERVAL '3 day')"

curl -X DELETE https://api.telemetry.sh/delete \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d @- <<EOF
{
  "table": "uber_rides",
  "where": "$WHERE_CONDITION"
}
EOF

If you want to delete the entire uber_rides table, simply omit the where field:

API_KEY="YOUR_API_KEY"

curl -X DELETE https://api.telemetry.sh/delete \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "uber_rides"
  }'

Important Notes

Data Deletion: Be careful when using the delete endpoint. If the where condition is not provided, the entire table will be deleted.
Irreversibility: Once data is deleted, it cannot be recovered.
Legacy endpoint: Prefer the Tables API for whole-table lifecycle operations when possible. DELETE /delete remains useful for row-level deletes with a where clause.

Common errors

400 Bad Request if the JSON body is invalid
400 Bad Request if the table name contains invalid characters after normalization
403 Forbidden if the API key only has read scope
401 Unauthorized if the API key is missing or invalid
404 Not Found if you try to delete rows from a table that has no schema yet
500 Internal Server Error if Telemetry fails to execute the delete request