Search and slices | Docs

Search runs over every processed segment in your organisation. Filters combine with AND; list values within one filter combine with OR.

Filters

Filter	Example	Matches
`site`	`"lab-2"`	Segments recorded at the site
`event`	`["grasp", "place"]`	Segments containing any of the interaction types
`object`	`"mug"`	Segments where an entity of that category appears
`text`	`"robot hands a cup to a person"`	Semantic match on the segment description
`near`	`{"point": [1.2, 0.4, 0.9], "radius_m": 0.5}`	Segments whose extent touches the region, in the site frame
`context`	`{"lighting": "low"}`	Context labels
`recorded`	`{"from": "2026-10-01", "to": "2026-10-15"}`	Recording time
`quality_min`	`{"psnr": 28}`	Segments at or above a quality score
`has_channels`	`["joints/position", "cam0/depth"]`	Segments carrying every listed channel

Searching

Python

results = client.segments.search(
    site=["lab-2", "lab-3"],
    event="grasp",
    object="mug",
    context={"lighting": "low"},
    quality_min={"psnr": 28},
)
print(results.total, "segments")
for seg in results[:3]:
    print(seg.id, seg.session, [e.type for e in seg.events()])

The same search over HTTP:

Shell

curl -G https://api.rayform.world/v1/segments \
  -H "Authorization: Bearer $RAYFORM_API_KEY" \
  --data-urlencode "site=lab-2,lab-3" \
  --data-urlencode "event=grasp" \
  --data-urlencode "object=mug" \
  --data-urlencode "context.lighting=low" \
  --data-urlencode "quality_min.psnr=28"

Freezing a slice

A search result changes as you upload more data. Freeze it before you train:

Python

slice_ = client.slices.create(
    segments=results,                # or a query: query={"event": "grasp", ...}
    name="mug grasps, low light",
)
print(slice_.id, slice_.segment_count)

Text

slc_7c1e04aa 412

A slice records the exact segment versions it contains. Keep its ID with your experiment; loading it again returns the same bytes even after the sessions are reprocessed.

Train and evaluation splits

Hold out whole sites or days, not random frames, so the evaluation measures generalisation:

Python

train = client.slices.create(query={"site": ["lab-2", "lab-3"], "event": "grasp"}, name="train")
evaluate = client.slices.create(query={"site": "lab-4", "event": "grasp"}, name="eval, unseen site")