Tailstream

Ingest API

Send log events to Tailstream for real-time processing and visualization.

Send log events

POST /api/ingest/{streamId}

Sends log events to Tailstream using newline-delimited JSON format.

Parameters

Name Type Description
streamId string Required. The stream identifier.

Headers

Name Value Description
Authorization Bearer <INGEST_TOKEN> Required. An ingest token for authentication.
Content-Type application/x-ndjson Required. Must be set to NDJSON format.
Content-Encoding gzip Optional compression for bandwidth efficiency.

Request body

The request body should contain newline-delimited JSON (NDJSON). Each line must be a valid JSON object representing a log event.

Tailstream supports two log formats:

Format 1: Direct structured logs (legacy format)

Each line is a JSON object with log event fields directly at the top level.

Format 2: Wrapped logs with metadata (new format)

Each line is a JSON object with a log field containing the actual log content (string or JSON), and optional metadata fields like filename.

Event attributes

Common attributes (Format 1)

Name Type Description
host string Hostname or service name generating the event.
path string Request path or endpoint being accessed.
status integer HTTP status code (200, 404, 500, etc.).
ts integer Timestamp in milliseconds since epoch. Auto-generated if not provided.
rt number Response time in seconds (e.g., 0.047 for 47ms).
bytes integer Response size in bytes.
method string HTTP method (GET, POST, PUT, DELETE, etc.).
src string Source identifier (IP address, server name, container ID, etc.).
user_agent string User agent string from the client request.

Wrapped format attributes (Format 2)

Name Type Description
log string Required. The actual log content. Can be plain text or JSON string.
filename string Source file path where the log originated (e.g., /var/log/nginx/access.log).

Example Requests

Example 1: Direct structured logs (Format 1)

curl -X POST https://your-tailstream-instance.com/api/ingest/acme \
  -H "Content-Type: application/x-ndjson" \
  -H "Authorization: Bearer <INGEST_TOKEN>" \
  --data-binary @- << 'EOF'
{"ts": 1699999999123, "host": "app.example.com", "path": "/api/users", "method": "GET", "status": 200, "rt": 0.047, "bytes": 1234, "src": "web-1"}
{"host": "app.example.com", "path": "/api/orders", "method": "POST", "status": 201, "rt": 0.12, "bytes": 567, "src": "web-2"}
{"host": "app.example.com", "path": "/health", "method": "GET", "status": 200, "rt": 0.003, "bytes": 89, "src": "web-1"}
EOF

Example 2: Wrapped logs with metadata (Format 2)

curl -X POST https://your-tailstream-instance.com/api/ingest/acme \
  -H "Content-Type: application/x-ndjson" \
  -H "Authorization: Bearer <INGEST_TOKEN>" \
  --data-binary @- << 'EOF'
{"log": "192.168.1.1 - - [23/Oct/2025:10:00:00 +0000] \"GET /api/users HTTP/1.1\" 200 1024", "filename": "/var/log/nginx/access.log"}
{"log": "[2025-10-23 10:00:01] production.ERROR: Database connection failed", "filename": "/var/log/app/error.log"}
{"log": "{\"ts\": 1699999999456, \"host\": \"api.example.com\", \"status\": 500}", "filename": "/var/log/app/structured.log"}
EOF

Note: Both formats can be mixed in the same request. Tailstream automatically detects and processes each format appropriately.

Response Format

The ingest endpoint returns different responses based on the request outcome. Use the response examples below to understand the expected formats.

Rate Limits

  • Request rate limit: Per-organization limit on requests per minute
  • Backpressure limit: Returns 429 if server queue is full
  • Connection limit: Per-organization limit on concurrent connections

When rate limited, wait for the duration specified in the Retry-After header before retrying.

Integration Examples

See the Ingest Setup Guide for detailed examples with tabs for:

  • Vector
  • Fluent Bit
  • Node.js
  • Python
  • Go
  • Nginx access logs