LogFlux has two APIs. The Ingestion API is the cloud endpoint that receives encrypted logs. The Agent API is a local socket interface for sending logs to the agent running on your machine.
| Ingestion API | Agent API |
|---|
| Transport | HTTPS (multipart/mixed) | Unix socket or TCP (NDJSON) |
| Endpoint | POST /v1/ingest | /var/run/logflux-agent/agent.sock or 127.0.0.1:8765 |
| Authentication | API Key (Bearer {region}-lf_<key>) | None (Unix) or shared secret (TCP) |
| Encryption | Client encrypts before sending | Agent encrypts before forwarding |
| Entry types | 1-7 (all types) | 1-5 (Log, Metric, Trace, Event, Audit) |
| Batch limit | 1000 entries per request | 100 entries per batch |
| Used by | Agent, SDKs (direct mode) | SDKs (agent mode), plugins, custom apps |
- Ingestion API – Cloud REST API. Multipart/mixed format, encryption handshake, rate limits, regional endpoints.
- Agent API – Local socket API. Unix/TCP transport, NDJSON messages, authentication, batch submission.
Payload Schema (v2.0)
Both APIs accept the same JSON payload format. This is the JSON that gets compressed and encrypted before transmission. The server never sees plaintext.
Common Fields
Every payload contains these fields regardless of entry type:
| Field | Type | Required | Description |
|---|
v | string | Yes | Schema version, always "2.0" |
type | string | Yes | Entry type: log, metric, trace, event, audit, telemetry |
source | string | Yes | Originating service/component (max 256 chars) |
level | int | No | Syslog severity 1-8 (default: 7 = info) |
ts | string | No | RFC 3339 timestamp (default: ingestion time) |
attributes | object | No | User-defined string key-value pairs (max 50 keys, key max 64 chars, value max 256 chars) |
meta | object | No | SDK/system metadata (not user-facing) |
Log (type 1)
1
2
3
4
5
6
7
8
9
10
11
12
13
| {
"v": "2.0",
"type": "log",
"source": "api-server",
"level": 4,
"ts": "2026-03-18T14:30:45.789Z",
"message": "Connection timeout after 5s",
"logger": "db.pool",
"attributes": {
"request_id": "req_abc123",
"db_host": "primary.db.internal"
}
}
|
| Field | Type | Required | Description |
|---|
message | string | Yes | Log message (max 8,192 chars) |
logger | string | No | Logger name / category (max 256 chars) |
Metric (type 2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| {
"v": "2.0",
"type": "metric",
"source": "api-server",
"ts": "2026-03-18T14:30:45.789Z",
"name": "http.request.duration",
"value": 142.5,
"unit": "millisecond",
"kind": "distribution",
"attributes": {
"method": "GET",
"route": "/api/users",
"status": "200"
}
}
|
| Field | Type | Required | Description |
|---|
name | string | Yes | Metric name, dot-notation (e.g. http.request.duration) |
value | number | Yes | Numeric value |
unit | string | No | Unit: millisecond, second, byte, percent, per_second, etc. Default: none |
kind | string | No | counter, gauge, or distribution. Default: gauge |
Trace (type 3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| {
"v": "2.0",
"type": "trace",
"source": "api-server",
"ts": "2026-03-18T14:30:45.789Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"parent_span_id": "b3dc45a03e2d5b7e",
"operation": "http.server",
"name": "GET /api/users",
"start_time": "2026-03-18T14:30:45.789Z",
"end_time": "2026-03-18T14:30:45.932Z",
"duration_ms": 143,
"status": "ok",
"attributes": {
"http.method": "GET",
"http.status_code": "200"
}
}
|
| Field | Type | Required | Description |
|---|
trace_id | string | Yes | W3C Trace Context format (32 hex chars) |
span_id | string | Yes | Unique span identifier (16 hex chars) |
parent_span_id | string | No | Parent span ID (omit for root spans) |
operation | string | Yes | Operation category (e.g. http.server, db.query) |
name | string | Yes | Span name (max 256 chars, low cardinality) |
start_time | string | Yes | RFC 3339 span start |
end_time | string | Yes | RFC 3339 span end |
duration_ms | number | No | Convenience field (end - start) |
status | string | No | ok or error. Default: ok |
Event (type 4)
1
2
3
4
5
6
7
8
9
10
11
12
| {
"v": "2.0",
"type": "event",
"source": "auth-service",
"ts": "2026-03-18T14:30:45.789Z",
"event": "user.signup",
"attributes": {
"user_id": "usr_987",
"plan": "starter",
"method": "oauth_google"
}
}
|
| Field | Type | Required | Description |
|---|
event | string | Yes | Event name, dot-notation (e.g. user.signup, payment.failed) |
Audit (type 5)
Stored with Object Lock (GOVERNANCE mode, 365-day undeletable retention).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| {
"v": "2.0",
"type": "audit",
"source": "billing-service",
"level": 6,
"ts": "2026-03-18T14:30:45.789Z",
"action": "record.deleted",
"actor": "usr_456",
"actor_type": "user",
"resource": "invoice",
"resource_id": "inv_789",
"outcome": "success",
"attributes": {
"reason": "customer_request",
"ip": "10.0.1.42",
"previous_state": "active",
"new_state": "deleted"
}
}
|
| Field | Type | Required | Description |
|---|
action | string | Yes | What happened (e.g. record.deleted, permission.granted) |
actor | string | Yes | Who did it (user ID, service name, or system) |
actor_type | string | No | user, service, system, or api_key. Default: user |
resource | string | Yes | What was affected (e.g. invoice, user, api_key) |
resource_id | string | Yes | Identifier of affected resource |
outcome | string | No | success, failure, or denied. Default: success |
Telemetry (types 6 and 7)
Type 6 uses E2E encryption. Type 7 (TelemetryManaged) uses server-side encryption only – same payload schema, different X-LF-Entry-Type header.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| {
"v": "2.0",
"type": "telemetry",
"source": "edge-gateway-01",
"ts": "2026-03-18T14:30:45.789Z",
"device_id": "dev_001",
"readings": [
{"name": "cpu_temp", "value": 72.5, "unit": "celsius"},
{"name": "memory_used", "value": 85.2, "unit": "percent"},
{"name": "disk_iops", "value": 1250, "unit": "per_second"}
],
"attributes": {
"firmware": "2.1.0",
"region": "eu-west-1"
}
}
|
| Field | Type | Required | Description |
|---|
device_id | string | Yes | Device/sensor identifier (max 256 chars) |
readings | array | Yes | Measurement objects (max 100) |
readings[].name | string | Yes | Reading name |
readings[].value | number | Yes | Measurement value |
readings[].unit | string | No | Unit (same options as Metric type) |
Attributes
The attributes object is a flat string-value map available on every entry type:
| Constraint | Value |
|---|
| Max keys per entry | 50 |
| Key length | 1-64 chars, lowercase, dots/underscores |
| Value length | 1-256 chars (numbers converted to strings) |
| Reserved prefix | lf.* (LogFlux internal) |
Follow OpenTelemetry semantic conventions where applicable: http.method, http.status_code, db.system, user.id, service.name, deploy.environment.
Entry Types
| Type | Name | Category | Encryption | Pricing |
|---|
| 1 | Log | Events | E2E (AES-256-GCM) | Events |
| 2 | Metric | Events | E2E (AES-256-GCM) | Events |
| 3 | Trace | Traces | E2E (AES-256-GCM) | Traces |
| 4 | Event | Events | E2E (AES-256-GCM) | Events |
| 5 | Audit | Audit | E2E (AES-256-GCM) + Object Lock | Audit |
| 6 | Telemetry | Traces | E2E (AES-256-GCM) | Traces |
| 7 | TelemetryManaged | Traces | Server-side (S3 SSE-KMS) | Traces |
Entry types affect pricing category and storage behavior.
Payload Types
| Value | Name | Used By | Description |
|---|
| 1 | aes256-gcm-gzip-json | Types 1-6 (default) | AES-GCM encrypted, gzip-compressed JSON |
| 2 | aes256-gcm-zstd-json | Types 1-6 | AES-GCM encrypted, zstd-compressed JSON |
| 3 | gzip-json | Type 7 only | Gzip-compressed JSON (no client encryption) |
| 4 | zstd-json | Type 7 only | Zstd-compressed JSON (no client encryption) |
Size Limits
| Limit | Value |
|---|
| Max payload (JSON before compression) | 1 MiB |
| Max entries per request | 1,000 |
| Max request body | 10 MiB |
Max message / event / action field | 8,192 chars |
| Max attribute key | 64 chars |
| Max attribute value | 256 chars |
| Max attributes per entry | 50 |
| Max telemetry readings | 100 |