Ingesting logs

You can use Better Stack even if there's no official library for your programming language by sending your logs to our HTTP API.

This endpoint allows you to log a single event or a list of events. The events can be encoded in JSON or preferably in a more efficient MessagePack.

Unauthorized

Couldn't parse JSON content.

payload reached size limit

Examples

Single event

Send a single log line using cURL:

curl -X POST https://$INGESTING_HOST \
     -H "Authorization: Bearer $SOURCE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message":"logs is ready","nested":{"values":123}}'

curl -X POST https://$INGESTING_HOST \
     -H "Authorization: Bearer $SOURCE_TOKEN" \
     -H "Content-Type: application/x-ndjson" \
     -d '{"message":"logs is ready","nested":{"values":123}}'

# Python is required to prepare the binary data in this example
python3 -c 'import msgpack; \
     print(msgpack.packb( \
          {"message":"logs is ready","nested":{"values":123}} \
     ).hex())' \
     | xxd -r -p \
     | curl -X POST https://$INGESTING_HOST \
          -H "Authorization: Bearer $SOURCE_TOKEN" \
          -H "Content-Type: application/msgpack" \
          --data-binary @-

Multiple events

Send multiple log lines using cURL:

curl -X POST https://$INGESTING_HOST \
     -H "Authorization: Bearer $SOURCE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '[{"message":"A"},{"message":"B"}]'

curl -X POST https://$INGESTING_HOST \
     -H "Authorization: Bearer $SOURCE_TOKEN" \
     -H "Content-Type: application/x-ndjson" \
     -d $'{"message":"A"}\n{"message":"B"}'

# Python is required to prepare the binary data
python3 -c 'import msgpack; \
     print(msgpack.packb( \
          [{"message":"A"},{"message":"B"}] \
     ).hex())' \
     | xxd -r -p \
     | curl -X POST https://$INGESTING_HOST \
          -H "Authorization: Bearer $SOURCE_TOKEN" \
          -H "Content-Type: application/msgpack" \
          --data-binary @-

Sending timestamps

By default, the time of the event will be the time of receiving it. You can override this by including a field dt containing the event time either as:

• UNIX time in whole seconds, milliseconds, or nanoseconds.
  1672490759, 1672490759123, 1672490759123456000
• String formatted according to RFC 3339.
  2022-12-31T13:45:59.123456Z, 2022-12-31 13:45:59.123456+02:00

Alternatively, you can use ISO 8601, as it will most likely use a format compatible with RFC 3339. In MessagePack, you can also use the timestamp extension type.

In case the timestamp can't be parsed, we save it as a string, but revert to using the reception time as the event time.

curl -X POST https://$INGESTING_HOST \
     -H "Authorization: Bearer $SOURCE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message":"I have arrived on time","dt":"2023-08-09 07:03:30+00:00"}'

Request limits

The maximum allowed size of a single request is 10 MiB.

We recommend keeping a single log record under 100 KiB for the best experience.