LiveFeed (gRPC)

Low-latency, server-streamed updates for fleets and trailers. Authenticate once, then read a continuous stream of LiveUpdateResponse messages—regular data updates plus automatic heartbeat frames every 60 seconds to keep connections healthy.

Docs

Download the proto or explore related REST docs.

Download livefeed.proto Integration API Auth API

The same proto is used by server and clients; include it in your build to generate client code or load at runtime.

Quickstart

  1. Obtain a JWT from the Auth API using your Customer API key.
  2. Generate client code from livefeed.proto.
  3. Dial the gRPC endpoint with Authorization: Bearer <JWT>.
  4. Call Subscribe and read messages; ignore heartbeat frames where is_heartbeat = true. 
// Example (C# gRPC client)
var channel = GrpcChannel.ForAddress("https://<host>");
var client  = new LiveFeed.LiveFeedClient(channel);
using var headers = new Metadata { { "authorization", $"Bearer {jwt}" } };
using var call = client.Subscribe(new SubscribeRequest(), headers);

await foreach (var resp in call.ResponseStream.ReadAllAsync())
{
    // Heartbeats arrive every ~60s with is_heartbeat = true and no payload.
    if (resp.IsHeartbeat)
        continue;

    var update = resp.LiveUpdate;
    if (update == null) 
        continue;

    // Handle your update...
    var trailer = update.Trailer;
    var ts = update.Ts; // UTC    
}

Authentication

One-time authentication on subscribe

Send your JWT once with the Subscribe call. The server validates the token up front and enforces your entitlements for the lifetime of the stream—no per-message auth.

  • Include JWT in gRPC metadata
  • Server validates & authorizes
  • No per-message auth required
  • Reconnect if the stream is closed
authorization: Bearer <JWT>
Pass this header in the metadata of your Subscribe request.
Account Status: The server may close the stream if your access is revoked or your account permissions change. There is no idle timeout while connected.
Connection Requirements
Transport: HTTP/2 over TLS (gRPC standard)
  • Persistent connection: long-lived server stream over HTTP/2.
  • Keep-alives: server sends heartbeat frames every 60s; no client ack required.
  • Clients: gRPC or gRPC-Web (C#, Java, Go, Node.js, Python, etc.).
  • Environment: trust standard TLS certs; support ALPN negotiation for HTTP/2.
  • Proxy/firewall: allow persistent HTTP/2 on port 443.
  • Availability: reconnect automatically after network interruptions or entitlement changes.

Workflow

Open a gRPC channel and pass the JWT in authorization metadata.

Call Subscribe. The server validates entitlements and starts streaming LiveUpdateResponse messages.

Every ~60s the server sends a heartbeat (is_heartbeat = true, live_update = null) to keep the stream alive. Clients do not need to respond; simply ignore these frames and keep reading.

If your entitlements change or the connection drops, the server may close the stream. Reconnect with backoff and resume reading new updates.
Common gRPC Status Codes
  • OKStream ended normally
  • UnauthenticatedMissing or invalid JWT
  • PermissionDeniedEntitlement or account access changed
  • CancelledClient canceled the call or connection
  • UnavailableTransport dropped / server unavailable

Heartbeats

Behavior
  • Server sends a heartbeat every 60 seconds to every subscriber.
  • Heartbeat frame: LiveUpdateResponse with is_heartbeat = true and live_update = null.
  • No client acknowledgement is required; clients cannot disable heartbeats.
  • Disconnect policy: streams are only closed if access is revoked or account permissions change.

Tip: Track your own “last data update time” metric client-side if you want to detect long periods without non-heartbeat data.

Schema excerpt
message LiveUpdateResponse {
  bool is_heartbeat = 1;               // Heartbeat frame
  optional LiveUpdate live_update = 2; // Null when heartbeat = true
}

See the full livefeed.proto below for message details.

Schema

Overview

The livefeed.proto defines the LiveFeed.Subscribe RPC and all related messages. Use it to generate strongly-typed clients in your language of choice.

  • Service: LiveFeed
  • Method: Subscribe(SubscribeRequest) returns (stream LiveUpdateResponse)
  • Messages: LiveUpdateResponse, LiveUpdate, Trailer, Telemetry, Status
Artifacts
Download livefeed.proto View schema See REST endpoints

Same proto for server and clients; include it in your build to generate client code or load at runtime.

Support & Best Practices

Best Practices
  • Maintain one active LiveFeed stream per API key.
  • Use exponential backoff after cancellations or entitlement changes.
  • Handle messages quickly and delegate heavy work to background workers.
  • Ignore heartbeat frames and refresh JWTs proactively when convenient.
Contact

Questions or onboarding needs?

4SEE Support Team