# Slices

> Freeze a selection of exact segment versions so it always returns the same data.

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

## The slice object

```json
{
  "id": "slc_7c1e04aa",
  "object": "slice",
  "name": "mug grasps, low light",
  "hash": "sha256:7c1e04aa93f2...",
  "segment_count": 412,
  "duration_s": 2871.6,
  "query": { "site": ["lab-2", "lab-3"], "event": ["grasp"], "object": ["mug"], "context": { "lighting": "low" } },
  "sites": ["lab-2", "lab-3"],
  "channels": ["cam0/rgb", "cam0/depth", "joints/position", "joints/velocity"],
  "created_at": "2026-10-15T09:41:00Z"
}
```

A slice's `id` is derived from its `hash`, which covers the sorted segment versions and their assets. Two requests that freeze the same data return the same slice.

## Create a slice

```endpoint
POST /v1/slices
```

Freeze either a query, evaluated now, or an explicit list of segments.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | A label for people; does not affect the hash |
| `query` | object | one of | Search filters, as in [Search segments](https://rayform.world/docs/api/segments#search-segments) |
| `segments` | array | one of | Segment IDs, or `{ "id", "version" }` to pin older versions |
| `exclude` | array | no | Segment IDs to leave out |

#### Request

```bash
curl https://api.rayform.world/v1/slices \
  -H "Authorization: Bearer $RAYFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mug grasps, low light",
    "query": { "site": ["lab-2", "lab-3"], "event": ["grasp"], "object": ["mug"], "context": { "lighting": "low" } }
  }'
```

```python
slice_ = client.slices.create(
    name="mug grasps, low light",
    query={"site": ["lab-2", "lab-3"], "event": "grasp", "object": "mug", "context": {"lighting": "low"}},
)
```

#### Response

Returns the slice object. Creating a slice with a query that matches nothing returns `422` with code `empty_slice`.

## Retrieve a slice

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

## List a slice's segments

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

Returns the exact segment versions in the slice, paginated. Segments whose session was deleted are listed with `"status": "deleted"`.

```json
{
  "object": "list",
  "data": [
    { "id": "seg_4f0a", "version": "sv_9b21e7", "status": "available" },
    { "id": "seg_51c2", "version": "sv_02aa4f", "status": "available" }
  ],
  "has_more": true,
  "next_cursor": "c2xjXzUxYzI"
}
```

## List slices

```endpoint
GET /v1/slices
```

| Query | Type | Description |
| --- | --- | --- |
| `name` | string | Prefix match on the name |
| `limit`, `cursor` | | [Pagination](https://rayform.world/docs/api#pagination) |