Log

The Log API is how you ingest events into Telemetry. Use it for application events, user activity, metrics, or structured logs.

Telemetry accepts flexible JSON input, but it is not a pure pass-through endpoint. The API normalizes table names, fills in timestamps, and prunes null values, empty objects, and empty arrays before forwarding data to storage.

POST https://api.telemetry.sh/log

Headers

Body

Accepted data shapes

The API accepts:

• a single JSON object
• an array of JSON objects
• a JSON string that itself parses into a JSON object
• an array containing JSON objects and JSON strings that parse into JSON objects

The API rejects:

• top-level numbers, booleans, and null
• JSON strings that decode to non-object values such as arrays, numbers, booleans, or null
• arrays containing non-object, non-string items
• arrays containing JSON strings that decode to non-object values
• JSON payloads nested deeper than 64 levels
• empty event batches, data: []

Server-side normalization

When data contains JSON objects, Telemetry applies these rules before ingest:

• adds timestamp with the current UTC time if it is missing
• if timestamp is null, replaces it with the current UTC time
• if timestamp is a Unix timestamp integer or numeric string, interprets it as Unix seconds and converts it to RFC 3339
• removes timestamp_utc if present
• recursively removes null values, empty objects, and empty arrays. Keeps "", 0, and false.

Examples:

• Telemetry Events becomes telemetry_events
• timestamp: 1700000000 becomes an RFC 3339 timestamp string
• { "user": "alice", "meta": null } is stored without meta

Example usage with cURL

To send Uber ride data to a table named uber_rides using cURL, you can use the following command:

curl -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "uber_rides",
    "data": {
      "city": "paris",
      "price": 42
    }
  }'

Using the JavaScript SDK

The JavaScript SDK handles the API request for you:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

telemetry.log("uber_rides", {
  city: "paris",
  price: 42
});

Bulk logging

You can also pass in an array of objects to bulk ingest events. This is useful for limiting the number of requests to the API. For example, instead of:

telemetry.log("uber_rides", { a: 1 })

You can do:

telemetry.log("uber_rides", [{a: 1}, {a: 2}])

This will ingest the data as two rows.

Common errors

• 400 Bad Request if the JSON body is invalid
• 400 Bad Request if the table name contains invalid characters after normalization
• 400 Bad Request if data is not in a supported shape
• 400 Bad Request with code empty_batch if data is an empty array. Send at least one event; reducing the payload size does not fix this error.
• 400 Bad Request if a JSON string in data decodes to a non-object value
• 400 Bad Request if a Unix timestamp is outside the supported range
• 401 Unauthorized if the API key is missing or invalid
• 429 Too Many Requests if the API key exceeds the gateway rate limit