Segments | Docs

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

Search segments

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

Request

Shell

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

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.

Shell

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

List versions

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
}