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