# Segments

> Search and read the processed pieces of your recordings: scene, entities, events, robot state and channels.

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

## The segment object

```json
{
  "id": "seg_4f0a",
  "object": "segment",
  "version": "sv_9b21e7",
  "session": "ses_01JA8K2M9Q",
  "site": "lab-2",
  "t0_ns": 1728910931400000000,
  "t1_ns": 1728910938850000000,
  "duration_s": 7.45,
  "description": "A person lifts a blue mug from the counter and places it on the rack.",
  "channels": ["cam0/rgb", "cam0/depth", "joints/position", "joints/velocity"],
  "events": [
    { "type": "grasp", "t_ns": 1728910932610000000, "entities": ["ent_hand_r", "ent_mug_1"] },
    { "type": "place", "t_ns": 1728910937020000000, "entities": ["ent_mug_1", "ent_rack"] }
  ],
  "entities": [
    { "id": "ent_mug_1", "category": "mug", "moves": true },
    { "id": "ent_rack", "category": "dish_rack", "moves": false }
  ],
  "context": { "lighting": "daylight", "clutter": "medium", "people": 1 },
  "quality": { "psnr": 31.2, "coverage": 0.93 },
  "extent": { "min": [0.1, -0.6, 0.0], "max": [2.4, 1.1, 1.8] },
  "assets": {
    "scene": "sha256:ab12...",
    "collision": "sha256:77d0...",
    "objects": { "ent_mug_1": "sha256:5e9c..." }
  },
  "pipeline_version": "2026.10.2"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `version` | string | Changes whenever the segment is reprocessed |
| `t0_ns`, `t1_ns` | integer | Start and end, in nanoseconds on the session clock |
| `events` | array | Interaction events in time order |
| `entities` | array | People, objects and robots seen in the segment |
| `extent` | object | Bounding box in the site frame, in metres |
| `quality` | object | Reconstruction scores against held-out sensor frames |
| `assets` | object | Content hashes of stored files; fetch them with [Assets](https://rayform.world/docs/api/assets) |

## Search segments

```endpoint
GET /v1/segments
```

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `site` | string | Comma-separated sites |
| `event` | string | Comma-separated event types: `grasp`, `place`, `push`, `open_drawer`, `close_drawer`, `open_door`, `handover`, `pour`, `wipe` |
| `object` | string | Comma-separated entity categories |
| `text` | string | Natural-language description to match |
| `near` | string | `x,y,z,radius_m` in the site frame |
| `context.*` | string | Context labels, for example `context.lighting=low` |
| `recorded[gte]`, `recorded[lt]` | string | Recording time, ISO 8601 |
| `quality_min.*` | number | Minimum quality score, for example `quality_min.psnr=28` |
| `has_channels` | string | Comma-separated channels every result must carry |
| `session` | string | Only segments from this session |
| `limit`, `cursor` | | [Pagination](https://rayform.world/docs/api#pagination) |

#### Request

```bash
curl -G https://api.rayform.world/v1/segments \
  -H "Authorization: Bearer $RAYFORM_API_KEY" \
  --data-urlencode "site=lab-2" \
  --data-urlencode "event=grasp" \
  --data-urlencode "object=mug" \
  --data-urlencode "limit=2"
```

```python
results = client.segments.search(site="lab-2", event="grasp", object="mug")
```

#### Response

```json
{
  "object": "list",
  "total": 412,
  "data": [
    { "id": "seg_4f0a", "object": "segment", "version": "sv_9b21e7", "duration_s": 7.45 },
    { "id": "seg_51c2", "object": "segment", "version": "sv_02aa4f", "duration_s": 4.9 }
  ],
  "has_more": true,
  "next_cursor": "c2VnXzUxYzI"
}
```

## Retrieve a segment

```endpoint
GET /v1/segments/{id}
```

Returns the latest version. Pass `version=sv_...` to read an older one, for example the version a slice was frozen with.

```bash
curl "https://api.rayform.world/v1/segments/seg_4f0a?version=sv_9b21e7" \
  -H "Authorization: Bearer $RAYFORM_API_KEY"
```

## List versions

```endpoint
GET /v1/segments/{id}/versions
```

```json
{
  "object": "list",
  "data": [
    { "version": "sv_9b21e7", "pipeline_version": "2026.10.2", "created_at": "2026-10-14T13:58:47Z" },
    { "version": "sv_1d0c33", "pipeline_version": "2026.09.4", "created_at": "2026-09-30T08:12:05Z" }
  ],
  "has_more": false
}
```