Tail

curl -N "https://api.orbit.devotel.io/api/v1/tail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

id: 0
event: connected
data: {"type":"connected","data":{"organizationId":"org_2aX7kQ","backfill_count":100}}

id: 1757726400123-0
event: log
data: {"type":"log","ts":1757726400123,"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"}

: heartbeat

curl -N "https://api.orbit.devotel.io/api/v1/tail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

id: 0
event: connected
data: {"type":"connected","data":{"organizationId":"org_2aX7kQ","backfill_count":100}}

id: 1757726400123-0
event: log
data: {"type":"log","ts":1757726400123,"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"}

: heartbeat

Tailing request-log events — worked samples

GET /api/v1/tail opens a Server-Sent Events (SSE) connection and streams every API request handled for your tenant — status code, latency, and request metadata — sub-second after each response completes. It is the data source behind the Live tail toggle on the developer Request Logs page. The stream excludes health, readiness, and metrics probes, provider webhook ingress, and the tail endpoint itself, so what you see is your traffic only. Because the response is an event stream — not a JSON document — this page documents the frames and fields below; copy the cURL sample as written and the stream prints to your terminal.

GET /api/v1/tail

Authentication: API key (X-API-Key) or session JWT. The caller must hold the owner, admin, or developer role. If you cannot send headers — a browser EventSource — pass the credential as the token query parameter instead: a dv_-prefixed value is treated as an API key, any other value as a bearer JWT. From server code, always use the header; a credential in a URL ends up in access logs and proxy history. Query parameters

Parameter	Type	Notes
`token`	string	Header-free authentication for `EventSource` clients (see above). Omit when you can send `X-API-Key` or `Authorization`.
`lastEventId`	string	Resume cursor. Set it to the `id` of the last frame you received and the server replays what you missed before continuing the live tail. Equivalent to the `Last-Event-ID` request header, which browser `EventSource` sends automatically on reconnect.

Open the stream with cURL

curl -N "https://api.orbit.devotel.io/api/v1/tail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

-N disables curl’s output buffering. Without it, the frames arrive but stay invisible until curl’s output buffer fills. The Accept header makes the SSE intent explicit. The query-parameter table above documents token and lastEventId; use headers whenever your client can send them.

Read the stream from Node.js

Use fetch when you need the raw SSE response; the generated SDK request helper buffers responses and cannot consume a never-ending stream. The parser below keeps the { event, id, data } frame shape and sends the latest lastEventId cursor on the next connection.

const url = "https://api.orbit.devotel.io/api/v1/tail";
const headers = {
  "X-API-Key": process.env.ORBIT_API_KEY,
  Accept: "text/event-stream",
};

async function readTail(lastEventId) {
  const requestUrl = lastEventId
    ? `${url}?lastEventId=${encodeURIComponent(lastEventId)}`
    : url;
  const response = await fetch(requestUrl, { headers });
  if (!response.ok || !response.body) {
    throw new Error(`Tail connection failed: ${response.status}`);
  }

  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  let frame = { event: "message", id: "", data: "" };
  let cursor = lastEventId;
  let pending = "";
  const flush = () => {
    if (!frame.data) return;
    const parsed = { ...frame, data: JSON.parse(frame.data) };
    if (parsed.id) cursor = parsed.id;
    console.log(parsed); // { event, id, data }
    frame = { event: "message", id: "", data: "" };
  };

  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      flush();
      return cursor;
    }
    pending += value;
    const lines = pending.split("\\n");
    pending = lines.pop() ?? "";
    for (const line of lines) {
      if (line === "") flush();
      else if (line.startsWith(": ")) continue;
      else if (line.startsWith("event: ")) frame.event = line.slice(7);
      else if (line.startsWith("id: ")) frame.id = line.slice(4);
      else if (line.startsWith("data: ")) frame.data += line.slice(6);
    }
  }
}

let lastEventId;
lastEventId = await readTail(lastEventId);

Read the stream from Python

requests exposes each SSE line as it arrives. Keep event, id, and data until the blank line terminates a frame, then parse the JSON data.

import json
import os
import requests

url = "https://api.orbit.devotel.io/api/v1/tail"
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Accept": "text/event-stream"}
frame = {"event": "message", "id": "", "data": ""}
last_event_id = None

with requests.get(url, headers=headers, stream=True, timeout=(10, None)) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if not line:
            if frame["data"]:
                print({**frame, "data": json.loads(frame["data"])})
                last_event_id = frame["id"] or last_event_id
            frame = {"event": "message", "id": "", "data": ""}
        elif line.startswith(":"):
            continue  # heartbeat comment
        elif line.startswith("event: "):
            frame["event"] = line[7:]
        elif line.startswith("id: "):
            frame["id"] = line[4:]
        elif line.startswith("data: "):
            frame["data"] += line[6:]

Frame sequence

After connecting, the server sends, in order:

An event: connected handshake frame carrying the organization id.
A backfill of up to the most recent ~100 request rows, each an event: log frame.
New event: log rows live, as each request completes.

Comment lines (: heartbeat) arrive every 30 seconds to keep the connection open. The first frames

id: 0
event: connected
data: {"type":"connected","data":{"organizationId":"org_2aX7kQ","backfill_count":100}}

id: 1757726400123-0
event: log
data: {"type":"log","ts":1757726400123,"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"}

: heartbeat

The response has no { data, meta } envelope — it is Content-Type: text/event-stream, so every frame above IS the response body. Log event fields — each log frame’s data: line is one JSON object:

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. Named frames mean a generic onmessage handler never sees the rows — register a log listener:

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

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

let cursor; // persist the last id across restarts

source.addEventListener("log", (event) => {
  cursor = event.id;
  forward(JSON.parse(event.data)); // your sink: log shipper, SIEM, on-call bot
});

source.onerror = () => {
  source.close();
  setTimeout(connect, backoff()); // EventSource re-sends Last-Event-ID = cursor
};

Resume after a disconnect

Every log frame carries an id (a stream cursor). To resume without losing rows, reconnect with Last-Event-ID or pass the same value as lastEventId. The loop below rehydrates the cursor after a dropped socket and increases the delay between attempts.

Node.js

let cursor;
let delay = 1_000;

while (true) {
  try {
    cursor = await readTail(cursor);
    delay = 1_000;
  } catch (error) {
    console.error(error);
    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 30_000);
  }
}

EventSource sends Last-Event-ID automatically when it reconnects. For an explicit request, pass the same cursor as lastEventId:

cURL

curl -N "https://api.orbit.devotel.io/api/v1/tail?lastEventId=1757726400123-0" \
  -H "X-API-Key: dv_live_sk_your_key_here"

The server replays the rows newer than that cursor, then continues the live tail. EventSource cannot set request headers, so use the documented token query parameter only in browser code. Prefer a short-lived credential and do not use this form in server code, where URLs may be logged.

Browser

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

source.addEventListener("connected", (event) => {
  console.log({ event: "connected", id: event.lastEventId, data: JSON.parse(event.data) });
});
source.addEventListener("log", (event) => {
  console.log({ event: "log", id: event.lastEventId, data: JSON.parse(event.data) });
});
source.onerror = () => console.warn("Tail connection dropped; EventSource will reconnect");

Limits and errors

Status	Meaning
`403`	Caller lacks the `owner`/`admin`/`developer` role, or (for browser clients) the request did not come from a trusted origin.
`429`	The 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.

This is a live tail, not durable history. For a longer-horizon export of the same rows, route through your own sink (as in the Node.js sample) instead of polling the stream.

Response sample — first frames as JSON

The SSE stream on the wire is the text sample above. For tooling that wants the same two frames as a parsed body, treat each frame’s data: line as one JSON object in arrival order:

{
  "event": "connected",
  "id": "0",
  "data": {
    "type": "connected",
    "data": { "organizationId": "org_2aX7kQ", "backfill_count": 100 }
  }
}

The second frame (event: log) carries the per-request row documented in the field table above; id advances so Last-Event-ID resumes cleanly after a reconnect.

API Reference

All Endpoints

Tailing request-log events — worked samples

Open the stream with cURL

Read the stream from Node.js

Read the stream from Python

Frame sequence

Resume after a disconnect

Limits and errors

Response sample — first frames as JSON

​Tailing request-log events — worked samples

​Open the stream with cURL

​Read the stream from Node.js

​Read the stream from Python

​Frame sequence

​Subscribe from Node.js with EventSource

​Resume after a disconnect

​Subscribe from a browser

​Limits and errors

​Response sample — first frames as JSON

Tailing request-log events — worked samples

Open the stream with cURL

Read the stream from Node.js

Read the stream from Python

Frame sequence

Subscribe from Node.js with EventSource

Resume after a disconnect

Subscribe from a browser

Limits and errors

Response sample — first frames as JSON