# Event streams

> Stream a segment's channels and events as Arrow record batches over Arrow Flight.

Source: https://rayform.world/docs/api/streams
Last updated: 2026-10-18
Status: Rayform is in private preview. APIs, formats and the SDK described here may change before general availability.

For reading time series at volume, such as joint states, IMU, poses and events, use the Arrow Flight endpoint instead of JSON. Data arrives as Arrow record batches that load directly into PyArrow, Polars or pandas without parsing.

## Endpoint

```endpoint
FLIGHT grpc+tls://flight.rayform.world:443
```

Authenticate with your API key as a bearer token in the call headers.

## Tickets

A ticket is a JSON object naming what to stream:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `segment` | string | yes | Segment ID |
| `version` | string | no | Segment version; defaults to the latest |
| `channels` | array | yes | Channels to stream, or `["events"]` for interaction events |
| `t0_ns`, `t1_ns` | integer | no | Time window; defaults to the whole segment |
| `frame` | string | no | Output convention, as in [export options](https://rayform.world/docs/guides/exporting#options) |

## Reading with PyArrow

```python
import json
import os

import pyarrow.flight as flight

client = flight.FlightClient("grpc+tls://flight.rayform.world:443")
options = flight.FlightCallOptions(headers=[(b"authorization", f"Bearer {os.environ['RAYFORM_API_KEY']}".encode())])

ticket = flight.Ticket(json.dumps({"segment": "seg_4f0a", "channels": ["joints/position", "joints/velocity"]}).encode())
table = client.do_get(ticket, options).read_all()
print(table.schema)
```

```text
t_ns: int64
joints/position: fixed_size_list<item: float>[7]
joints/velocity: fixed_size_list<item: float>[7]
```

## Reading with the SDK

The SDK wraps the same calls:

```python
seg = client.segments.get("seg_4f0a")
joints = seg.channel("joints/position")          # pyarrow.Table
events = seg.events()                             # pyarrow.Table, time-ordered
```

## Event schema

| Column | Type | Description |
| --- | --- | --- |
| `t_ns` | int64 | Event time on the session clock |
| `type` | string | Event type, for example `grasp` |
| `entities` | list of string | Entity IDs involved |
| `t_start_ns`, `t_end_ns` | int64 | Span of the interaction |
| `confidence` | float32 | Detector confidence, from 0 to 1 |