Send JSON Events

Use an events dataset for application events that are not OpenTelemetry data. Examples are sign-ups, payments, finished jobs, and feature use.

You send each event as a JSON object in an HTTP request. Telemetry Machine adds a column for each new field. You do not define a schema before you send events.

Before you start

• You must have a Telemetry Machine account and an organization.
• To create a dataset or an API key, you must be an owner or an admin of the organization.
• To use the commands on this page, install tm-cli. Then sign in. Refer to Quick Start.

Create an events dataset

You can create the dataset in the application or with tm-cli.

In the application

The application shows the full API key one time only. To send events with the key, refer to Send events.

With tm-cli

Create the dataset:

$ tm-cli datasets create --name checkout-events --type events

Create an API key that can write to the dataset:

$ tm-cli api-keys create --name checkout-backend --dataset checkout-events

The output shows the full key in api_key.api_key. It shows the full key one time only.

Dataset names

• Use only lowercase letters, digits, hyphens (-), and underscores (_).
• Do not use a period (.) in the name.
• You cannot use the name of a deleted dataset again.

Create an API key

The application makes an API key when it creates a dataset. To make a different key, do these steps:

An API key can send data only. It cannot read data. One key can write to more than one dataset, but each request sends events to one dataset.

Send events

Send a POST request to this endpoint:

https://api.telemetrymachine.com/v1/events

Headers

Use Idempotency-Key if you send a request again after an error. Refer to Send a request again.

Body

The body can have one of these forms:

• One JSON object, with Content-Type: application/json.
• A JSON array of objects, with Content-Type: application/json.
• One JSON object on each line (NDJSON), with Content-Type: application/x-ndjson.

Send only JSON objects. Telemetry Machine does not keep array items or lines that are not objects. If one NDJSON line is not valid JSON, Telemetry Machine rejects the full request.

Example

This request sends one event:

curl https://api.telemetrymachine.com/v1/events \
  -H "X-API-Key: $TM_API_KEY" \
  -H "X-Dataset-Name: checkout-events" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c2f0e9a-3b1d-4f7e-9a58-0d4b1c7e2a91" \
  -d '{
    "timestamp": "2026-10-08T12:00:00Z",
    "uuid": "0b8e7c52-6d1f-4a3e-b9c4-5f2a8d1e7c60",
    "event": "order.paid",
    "order": { "id": "A-1042", "total": 129.5, "currency": "EUR" },
    "user": { "id": 77, "plan": "pro" }
  }'

This request sends a compressed NDJSON file:

gzip -c events.ndjson | curl https://api.telemetrymachine.com/v1/events \
  -H "X-API-Key: $TM_API_KEY" \
  -H "X-Dataset-Name: checkout-events" \
  -H "Content-Type: application/x-ndjson" \
  -H "Content-Encoding: gzip" \
  --data-binary @-

Event fields

This figure shows how the example event from Send events becomes one row:

Event time

Put the time of the event in timestamp. Use one of these forms:

Telemetry Machine finds the unit from the size of the number. You can also send the number as a string, for example "1791460800".

A date must have a time zone: Z or an offset, for example +02:00. Telemetry Machine rejects a date without a time zone, for example 2026-10-08T12:00:00.

If an event does not have timestamp, Telemetry Machine uses the time that it received the event.

Event ID

Put an ID for the event in uuid or event.uuid. Use a different ID for each event. Telemetry Machine keeps the ID in the event.uuid column. If the event does not have an ID, Telemetry Machine makes one.

Field names

Each field becomes a column with the same name. For a field in a nested object, the column name is the keys with a period between them:

{"order": {"id": "A-1042"}}   →   order.id = "A-1042"

A key that contains a period gives the same column. {"order.id": "A-1042"} also gives order.id. If one event has the two forms of the same name, Telemetry Machine rejects the event.

Telemetry Machine reads objects to a depth of 5 levels. It keeps a deeper object as JSON text in one column. It keeps an array as JSON text in one column.

Field types

The values in the first request that contains a field set the type of its column:

The type of a column does not change after Telemetry Machine creates it. If a value does not fit the type, Telemetry Machine rejects the event. Examples:

• A Double column keeps integers.
• A Utf8 column keeps all values. It keeps numbers and booleans as text.
• An Int64 column rejects 2.5. It also rejects strings, for example "5".

Telemetry Machine does not read numbers or dates in strings. The value "42" is text.

You cannot change the type of a column. If a column has an incorrect type, send the value in a field with a new name.

Columns that Telemetry Machine fills

Each events dataset has these columns. Telemetry Machine fills them for each event:

Telemetry Machine replaces the values that you send for _time, ingested_at, _tenant_id, and _source.

Read the response

Status codes

The message Invalid API key has one of these causes:

• The API key is not correct, or it does not exist.
• X-Dataset-Name is not the name of a dataset.
• The API key cannot write to the dataset.

Accepted and rejected events

This response shows a request with 3 events. Telemetry Machine kept 2 events and rejected 1 event:

{
  "status": "partial",
  "ingested": 2,
  "rejected": 1,
  "errors": [
    {
      "event": 3,
      "column": "order.total",
      "code": "column.type_mismatch",
      "message": "the value does not fit the column's type Double"
    }
  ]
}

• ingested is the number of events that Telemetry Machine kept.
• rejected is the number of events that Telemetry Machine did not keep.
• errors gives the cause for rejected events. It shows a maximum of 16 events for each 3.5 MiB of the request.
• event is the position of the event in the request. The first event is 1.

Telemetry Machine does not keep a rejected event. If you send the same event again with no change, Telemetry Machine rejects it again.

Rejection codes

Send a request again

Send a request again if the status is 429, 500, or 503, or if you do not get a response.

If you send the same request with the same key in less than 5 minutes, Telemetry Machine does not keep its events again. It sends the first response again.

Telemetry Machine keeps a large request in parts. If one part fails, send the full request again with the same key. Telemetry Machine does not keep the other parts two times.

If a request does not have Idempotency-Key, Telemetry Machine reads it as a new request. If you send it again, the dataset can have its events two times.

Limits

If a request goes above a limit, Telemetry Machine rejects the full request. The status is 413 for the body size, 429 for the request rate, and 400 for the other limits.

Query your events

Events are usually available to queries a few seconds after a success response. Sometimes this takes a maximum of 30 seconds.

To see your events in the application, open Query. Then select your events dataset.

To see the columns of the dataset with tm-cli:

$ tm-cli schema get checkout-events --type events

To query the events of the last hour:

$ tm-cli query checkout-events --type events --since 1h --limit 20

Troubleshooting

FAQ