Live request-log tail

GET /api/v1/logs/tail opens a Server-Sent Events (SSE) connection that streams every API request handled for your tenant, sub-second after each response completes. It is the data source behind the Live tail toggle on the developer Request Logs page, and you can consume it directly from your own tooling. The stream excludes health, readiness, and metrics probes, provider webhook ingress (those receiver 401s are provider-side noise, not your API traffic), and the tail endpoint itself. Base path: /api/v1/logs/tail Authentication: API key (X-API-Key) or session JWT. The caller must hold the owner, admin, or developer role.

Using the SDKs

This endpoint has no typed SDK helper, and the generic request() escape hatch does not fit SSE: it buffers the whole body, waits for the response to complete, then returns it as one raw non-JSON string. A live tail never completes — the sample below honors the request timeout, returns the beginning of the stream as a chunk of raw text/event-stream, and disconnects. Anything you persisted would be only the backfill:

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

// Returns a chunk of raw SSE text, NOT the stream — held open for
// `timeout` ms of nothing received, then disconnected. One-way only;
// you cannot consume frames through request().
const raw = await orbit.request<unknown>("GET", "/logs/tail");

Consume the stream over raw HTTP instead — the per-language loops below open the connection and parse event: log frames as they arrive. Only browser customers use EventSource; every server-side consumer (Node fetch, Python requests, Go net/http, Ruby Net::HTTP, PHP cURL) is a plain GET plus an incremental frame parser. Full SDK index at SDK quickstart.

Connect

Browsers use EventSource, which cannot set request headers, so pass your credential as the token query parameter instead. A dv_-prefixed value is promoted to X-API-Key; any other value is treated as a bearer JWT. When you call from a server you can send the X-API-Key or Authorization header directly and omit token.

cURL

curl -N "https://api.orbit.devotel.io/api/v1/logs/tail?token=dv_live_sk_your_key_here"

EventSource (browser)

const source = new EventSource(
  `https://api.orbit.devotel.io/api/v1/logs/tail?token=${jwt}`,
  { withCredentials: true },
);

source.addEventListener("log", (event) => {
  const row = JSON.parse(event.data);
  console.log(row.method, row.path_pattern, row.status_code, row.duration_ms);
});

SSE frame

event: log
id: 1718971200123-0
data: {"type":"log","ts":1718971200123,"request_id":"req_7f3c2a","method":"POST","path_pattern":"/api/v1/messages","status_code":202,"duration_ms":41,"user_id":"user_abc","api_key_id":null,"error_code":null,"error_message":null,"user_agent":"MyApp/1.4"}

Worked example: read status and latency off the stream

The frame format to parse is exactly the payload above — a named event: log line, an id: cursor line, and one data: line holding a single JSON envelope per frame (multi-line data: is legal per the SSE spec but this endpoint always sends a single line). This Python loop opens the stream, splits frames on a blank line, and extracts status_code + duration_ms off each log row — the same fields you would chart in an error-rate or latency dashboard:

import json
import os

import requests

last_event_id = None  # persist this across restarts for resume

def parse_frame(lines):
    """Split one SSE frame into (event, data, id)."""
    event, data, frame_id = "message", "", None
    for line in lines:
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line.startswith("id:"):
            frame_id = line[3:].strip()
    return event, data, frame_id

def consume():
    global last_event_id
    headers = {
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Accept": "text/event-stream",
    }
    if last_event_id:
        headers["Last-Event-ID"] = last_event_id

    with requests.get(
        "https://api.orbit.devotel.io/api/v1/logs/tail",
        headers=headers,
        stream=True,
    ) as response:
        response.raise_for_status()
        lines = []
        for line in response.iter_lines(decode_unicode=True):
            if line == "":  # blank line ends the frame
                event, data, frame_id = parse_frame(lines)
                lines = []
                if event != "log" or not data:
                    continue  # handshake + heartbeats carry no row
                if frame_id is not None:
                    last_event_id = frame_id
                row = json.loads(data)
                yield row["status_code"], row["duration_ms"], row["path_pattern"]

for status, latency_ms, route in consume():
    if status >= 400:
        print(f"{route} -> {status} in {latency_ms} ms")

The loops below generalize this into reconnect + cursor persistence per language.

Frames

After connecting, the server sends, in order:

An event: connected handshake frame with data: {"type":"connected", ...}.
A backfill of up to the most recent ~100 request rows.
New rows live, as each request completes.

Comment lines (: heartbeat) are sent every 30 seconds to keep the connection open. Each request row arrives as a named log frame — listen with addEventListener("log", …), not onmessage, because EventSource only routes named frames to a matching listener. Each log frame’s data: line is one JSON object:

{
  "type": "log",
  "ts": 1718971200123,
  "request_id": "req_7f3c2a",
  "method": "POST",
  "path_pattern": "/api/v1/messages",
  "status_code": 202,
  "duration_ms": 41,
  "user_id": "user_abc",
  "api_key_id": null,
  "error_code": null,
  "error_message": null,
  "user_agent": "MyApp/1.4"
}

Field	Type	Notes
`type`	string	Always `log`.
`ts`	integer	Unix epoch milliseconds when the response completed.
`request_id`	string	Per-request id, also returned as the `X-Request-Id` header.
`method`	string	HTTP method.
`path_pattern`	string	Normalized route with ids collapsed to `:id`, e.g. `/api/v1/messages/:id`.
`status_code`	integer	HTTP status code.
`duration_ms`	integer	Server-side handling time in milliseconds.
`user_id`	string \| null	Authenticated user, or `null` for API-key requests.
`api_key_id`	string \| null	API key that authenticated the request, or `null`.
`error_code`	string \| null	Machine-readable error code for `>= 400` responses, otherwise `null`.
`error_message`	string \| null	Error message for `>= 400` responses (truncated), otherwise `null`.
`user_agent`	string \| null	Request `User-Agent` (truncated), or `null`.

Adding fields is backwards-compatible — ignore keys you don’t recognize, and drop any row missing a required field.

Resume after a disconnect

Every frame carries an id (a stream cursor). To resume without losing rows, reconnect with the Last-Event-ID request header set to the last id you received — browser EventSource does this automatically. From a client that can’t set the header, pass the same value as the lastEventId query parameter:

curl -N "https://api.orbit.devotel.io/api/v1/logs/tail?token=dv_live_sk_your_key_here&lastEventId=1718971200123-0"

On resume the server replays the rows newer than that cursor before continuing the live tail.

Consume the SSE stream from code

Server-side consumers — log forwarders, ETL jobs, on-call bots — authenticate with the X-API-Key header (or an Authorization bearer header). Never send token as a query parameter from server code: a URL ends up in access logs and proxy history, and a credential in it is exposed. If your server library parses named SSE events, use the named event (addEventListener("log", …)), not a generic message handler — the rows arrive as event: log frames, so an onmessage-style handler never sees them. The curl sample above is a one-off tail; the sections below are the full client loops you keep in your own tooling. The sections below give a full client loop per language — header auth, frame parsing, cursor persistence, and reconnect — for Node.js, Python, Go, Ruby, and PHP.

Node.js

eventsource
Manual parse (fetch)

// npm install eventsource
import { EventSource } from "eventsource";

let cursor = loadCursor(); // persist the last id across restarts

function connect() {
  const source = new EventSource("https://api.orbit.devotel.io/api/v1/logs/tail", {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY },
  });

  // Named listener — the log rows arrive as `event: log` frames.
  source.addEventListener("log", (event) => {
    cursor = event.id;
    saveCursor(cursor); // persist for resume after a disconnect
    forward(JSON.parse(event.data)); // your sink: Kafka, BigQuery, SIEM…
  });

  source.onerror = () => {
    source.close();
    setTimeout(connect, backoff()); // then reconnect with Last-Event-ID
  };
}

Manual parsing is one pattern: buffer the stream, split frames on a blank line, and read each frame’s event, data, and id fields:

let cursor = loadCursor();

async function connect() {
  const headers = { "X-API-Key": process.env.ORBIT_API_KEY, Accept: "text/event-stream" };
  if (cursor) headers["Last-Event-ID"] = cursor;

  const response = await fetch("https://api.orbit.devotel.io/api/v1/logs/tail", { headers });
  if (!response.ok) throw new Error(`tail ${response.status}`);

  let buffer = "";
  for await (const chunk of response.body) {
    buffer += chunk.toString("utf8");
    let frameEnd; // a blank line terminates each frame
    while ((frameEnd = buffer.indexOf("\n\n")) >= 0) {
      const frame = buffer.slice(0, frameEnd);
      buffer = buffer.slice(frameEnd + 2);
      let event = "message", data = "", id;
      for (const line of frame.split("\n")) {
        if (line.startsWith("event:")) event = line.slice(6).trim();
        else if (line.startsWith("data:")) data += line.slice(5).trim();
        else if (line.startsWith("id:")) id = line.slice(3).trim();
      }
      if (event === "log" && data) {
        cursor = id ?? cursor;
        saveCursor(cursor);
        forward(JSON.parse(data));
      }
    }
  }
}

Python

sseclient dispatches each frame’s event: field to callbacks you register per name — register log, not message. With requests you iterate lines and track the fields yourself:

sseclient
requests

# pip install sseclient requests
import os
import json
import requests
import sseclient

cursor = load_cursor()

response = requests.get(
    "https://api.orbit.devotel.io/api/v1/logs/tail",
    headers={
        # header auth — never put the credential in the URL
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Accept": "text/event-stream",
        # resume token — re-send the last id you saved
        "Last-Event-ID": cursor,
    },
    stream=True,
)
client = sseclient.SSEClient(response)

@client.on_event("log")  # named listener — the rows are `event: log`
def handle_log(event):
    save_cursor(event.id)
    forward(json.loads(event.data))

for _event in client.events():
    pass

import os, json, requests

cursor = load_cursor()
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Accept": "text/event-stream"}
if cursor:
    headers["Last-Event-ID"] = cursor

with requests.get(
    "https://api.orbit.devotel.io/api/v1/logs/tail",
    headers=headers,
    stream=True,
) as response:
    event, data, event_id = "message", "", None
    for line in response.iter_lines(decode_unicode=True):
        if line == "":  # blank line terminates one frame
            if event == "log" and data:
                save_cursor(event_id)
                forward(json.loads(data))
            event, data, event_id = "message", "", None
        elif line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line.startswith("id:"):
            event_id = line[3:].strip()

Go

go-sse subscribes per event name and re-sends the last id itself while reconnecting — subscribe to log, not the unnamed default. With the standard library you scan lines with bufio and track the fields yourself:

go-sse
Manual parse (net/http)

// go get github.com/tmaxmax/go-sse
package main

import (
  "encoding/json"
  "net/http"
  "os"

  "github.com/tmaxmax/go-sse"
)

func connect() {
  cursor := loadCursor() // persist the last id across restarts

  req, err := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/logs/tail", nil)
  if err != nil {
    return
  }
  // header auth — never put the credential in the URL
  req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
  // resume token — re-send the last id you saved
  req.Header.Set("Last-Event-ID", cursor)

  conn := sse.NewConnection(req)

  // Named subscription — the log rows arrive as `event: log` frames.
  conn.Subscribe("log", func(event sse.Event) {
    cursor = event.LastEventID
    saveCursor(cursor) // persist for resume after a disconnect
    var row map[string]any
    if err := json.Unmarshal([]byte(event.Data), &row); err == nil {
      forward(row) // your sink: Kafka, BigQuery, SIEM…
    }
  })

  _ = conn.Connect() // go-sse re-sends Last-Event-ID itself on reconnect
}

stdlib only — scan lines and track event, data, and id yourself:

package main

import (
  "bufio"
  "encoding/json"
  "net/http"
  "os"
  "strings"
)

func connect() {
  cursor := loadCursor()

  req, err := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/logs/tail", nil)
  if err != nil {
    return
  }
  req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
  req.Header.Set("Accept", "text/event-stream")
  if cursor != "" {
    req.Header.Set("Last-Event-ID", cursor)
  }

  resp, err := http.DefaultClient.Do(req)
  if err != nil || resp.StatusCode != http.StatusOK {
    return
  }
  defer resp.Body.Close()

  event, data, id := "message", "", ""
  scanner := bufio.NewScanner(resp.Body)
  for scanner.Scan() {
    line := scanner.Text()
    switch {
    case line == "": // a blank line terminates one frame
      if event == "log" && data != "" {
        cursor = id
        saveCursor(cursor)
        var row map[string]any
        if json.Unmarshal([]byte(data), &row) == nil {
          forward(row)
        }
      }
      event, data, id = "message", "", ""
    case strings.HasPrefix(line, "event:"):
      event = strings.TrimSpace(line[6:])
    case strings.HasPrefix(line, "data:"):
      data += strings.TrimSpace(line[5:])
    case strings.HasPrefix(line, "id:"):
      id = strings.TrimSpace(line[3:])
    }
  }
}

Ruby

em-eventsource dispatches named frames to per-name callbacks and re-sends the last id itself while reconnecting — register log, not the generic message handler. With Net::HTTP you buffer chunks, split lines, and track the fields yourself:

em-eventsource
Manual parse (Net::HTTP)

# gem install em-eventsource
require "em-eventsource"
require "json"

EventMachine.run do
  source = EventSource.new(
    "https://api.orbit.devotel.io/api/v1/logs/tail",
    { "X-API-Key" => ENV["ORBIT_API_KEY"] }, # header auth — never in the URL
  )

  # Named listener — the log rows arrive as `event: log` frames.
  source.on "log" do |message, event_id|
    save_cursor(event_id) # persist for resume after a disconnect
    forward(JSON.parse(message)) # your sink: Kafka, BigQuery, SIEM…
  end

  source.error do |_error|
    source.close # the next `start` re-sends Last-Event-ID itself
  end

  source.start
end

stdlib only — buffer the stream, split lines, and read each frame’s fields:

require "net/http"
require "json"

cursor = load_cursor
uri = URI("https://api.orbit.devotel.io/api/v1/logs/tail")
headers = { "X-API-Key" => ENV["ORBIT_API_KEY"], "Accept" => "text/event-stream" }
headers["Last-Event-ID"] = cursor if cursor

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request_get(uri.request_uri, headers) do |response|
    event, data, event_id = "message", +""
    buffer = +""
    response.read_body do |chunk|
      buffer << chunk
      while (line_end = buffer.index("\n"))
        line = buffer.slice!(0, line_end + 1).chomp
        if line == "" # a blank line terminates one frame
          if event == "log" && !data.empty?
            save_cursor(event_id)
            forward(JSON.parse(data))
          end
          event, data, event_id = "message", +""
        elsif line.start_with?("event:")
          event = line[6..].strip
        elsif line.start_with?("data:")
          data += line[5..].strip
        elsif line.start_with?("id:")
          event_id = line[3..].strip
        end
      end
    end
  end
end

PHP

Guzzle returns the body as a stream when you pass stream => true, so read it incrementally and track the fields yourself. The cURL extension takes a write callback — the manual-parse form without Guzzle:

Guzzle (stream)
Manual parse (cURL extension)

<?php
// composer require guzzlehttp/guzzle
$cursor = load_cursor(); // persist the last id across restarts

$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.orbit.devotel.io/api/v1/logs/tail", [
    "headers" => [
        // header auth — never put the credential in the URL
        "X-API-Key" => getenv("ORBIT_API_KEY"),
        "Accept" => "text/event-stream",
        // resume token — re-send the last id you saved
        "Last-Event-ID" => $cursor,
    ],
    "stream" => true, // read the body as it arrives instead of buffering
    "timeout" => 0,   // an SSE stream never completes; disable the timeout
]);

$body = $response->getBody();
$event = "message";
$data = "";
$id = null;
$buffer = "";
while (!$body->eof()) {
    $buffer .= $body->read(8192);
    while (($lineEnd = strpos($buffer, "\n")) !== false) {
        $line = rtrim(substr($buffer, 0, $lineEnd + 1));
        $buffer = substr($buffer, $lineEnd + 1);
        if ($line === "") { // a blank line terminates one frame
            if ($event === "log" && $data !== "") {
                save_cursor($id);
                forward(json_decode($data, true)); // your sink
            }
            $event = "message";
            $data = "";
            $id = null;
        } elseif (str_starts_with($line, "event:")) {
            $event = trim(substr($line, 6));
        } elseif (str_starts_with($line, "data:")) {
            $data .= trim(substr($line, 5));
        } elseif (str_starts_with($line, "id:")) {
            $id = trim(substr($line, 3));
        }
    }
}

a write callback receives each chunk as it arrives; buffer it and split frames on a blank line:

<?php
$cursor = load_cursor(); // persist the last id across restarts

$ch = curl_init("https://api.orbit.devotel.io/api/v1/logs/tail");
$headers = [
    "X-API-Key: " . getenv("ORBIT_API_KEY"), // header auth — never in the URL
    "Accept: text/event-stream",
];
if ($cursor) {
    $headers[] = "Last-Event-ID: $cursor";
}

$buffer = "";
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_TIMEOUT => 0, // an SSE stream never completes; disable the timeout
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$buffer, &$cursor) {
        $buffer .= $chunk;
        while (($frameEnd = strpos($buffer, "\n\n")) !== false) {
            $frame = substr($buffer, 0, $frameEnd);
            $buffer = substr($buffer, $frameEnd + 2);
            $event = "message";
            $data = "";
            $id = null;
            foreach (explode("\n", $frame) as $line) {
                if (str_starts_with($line, "event:")) $event = trim(substr($line, 6));
                elseif (str_starts_with($line, "data:")) $data .= trim(substr($line, 5));
                elseif (str_starts_with($line, "id:")) $id = trim(substr($line, 3));
            }
            if ($event === "log" && $data !== "") {
                $cursor = $id ?? $cursor;
                save_cursor($cursor); // persist for resume after a disconnect
                forward(json_decode($data, true));
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);

Keep the saved cursor in durable storage (a file, Redis, a database row) and re-send it as Last-Event-ID on reconnect — the server replays the rows you missed.

Limits and errors

Status	Meaning
`403`	Caller lacks the `owner`/`admin`/`developer` role, or the request did not come from a trusted browser origin.
`429`	Tenant has reached the maximum of 10 concurrent tail connections. Close an existing connection and retry.
`503`	The real-time backing store is temporarily unavailable. Retry with backoff.

On 429 or 503 from a server-side consumer, back off before retrying instead of reconnecting in a tight loop:

Node.js
Python

function backoff(attempt) {
  // 1s, 2s, 4s … capped at 30s; jitter spreads retries
  return Math.min(30_000, 1_000 * 2 ** attempt) + Math.random() * 500;
}

import random, time

def backoff(attempt):
    # 1s, 2s, 4s … capped at 30s; jitter spreads retries
    time.sleep(min(30, 2 ** attempt) + random.uniform(0, 0.5))

This is a live tail, not durable history. It carries only recent rows and the live stream — use it for observability, not as a system of record.

API Reference

All Endpoints

Live request-log tail

Live request-log tail

Using the SDKs

Connect

Worked example: read status and latency off the stream

Frames

Resume after a disconnect

Consume the SSE stream from code

Node.js

Python

Go

Ruby

PHP

Limits and errors

​Live request-log tail

​Using the SDKs

​Connect

​Worked example: read status and latency off the stream

​Frames

​Resume after a disconnect

​Consume the SSE stream from code

​Node.js

​Python

​Go

​Ruby

​PHP

​Limits and errors

Live request-log tail

Using the SDKs

Connect

Worked example: read status and latency off the stream

Frames

Resume after a disconnect

Consume the SSE stream from code

Node.js

Python

Go

Ruby

PHP

Limits and errors