> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chunk Retrieval

> Retrieve full-text chunks and neighboring context from processed vault objects

When vault search returns a truncated `text_preview`, use chunk retrieval to fetch the full chunk text and nearby chunks from the document manifest stored in Vault.

***

## Endpoint

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /vault/:id/objects/:objectId/chunks
```

## When to use it

Search is optimized for relevance and compact responses. That means results often contain only a preview of the matched chunk. If the match lands inside a table, exhibit list, or a passage that spans several chunks, call `read-chunks` to recover the surrounding text.

Example workflow:

1. Search returns chunk `13` with a partial exhibit table.
2. Request `start=12&end=14`.
3. Read the full text of chunks `12`, `13`, and `14` together.

<Info>
  Ranges are inclusive and capped at 10 chunks per request.
</Info>

## Parameters

| Parameter  | Type    | Required | Description                                                                            |
| ---------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | Vault ID                                                                               |
| `objectId` | string  | Yes      | Processed object ID                                                                    |
| `start`    | integer | No       | First chunk index to return. Defaults to `0`.                                          |
| `end`      | integer | No       | Last chunk index to return, inclusive. If omitted, only the `start` chunk is returned. |

## Example

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl "https://api.case.dev/vault/$VAULT_ID/objects/$OBJECT_ID/chunks?start=12&end=14" \
    -H "Authorization: Bearer $CASEDEV_API_KEY"
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const response = await client.api.get(
    `/vault/${vaultId}/objects/${objectId}/chunks`,
    {
      params: { start: 12, end: 14 },
    }
  )

  for (const chunk of response.chunks) {
    console.log(chunk.index, chunk.text)
  }
  ```
</CodeGroup>

```json title="Response" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "object_id": "obj_abc123",
  "vault_id": "vault_def456",
  "chunks": [
    {
      "index": 12,
      "text": "full text of chunk 12...",
      "page_start": 5,
      "page_end": 5,
      "word_start_index": 5544,
      "word_end_index": 6055
    },
    {
      "index": 13,
      "text": "full text of chunk 13...",
      "page_start": 5,
      "page_end": 6,
      "word_start_index": 6056,
      "word_end_index": 6532
    },
    {
      "index": 14,
      "text": "full text of chunk 14...",
      "page_start": 6,
      "page_end": 6,
      "word_start_index": 6533,
      "word_end_index": 6881
    }
  ],
  "total_chunks": 42
}
```

For media-backed transcripts, chunks can include source audio/video timing when real word timing is available:

```json title="Media transcript chunk" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "index": 0,
  "text": "Good morning. Could you please state your full name for the record?...",
  "page_start": null,
  "page_end": null,
  "word_start_index": 0,
  "word_end_index": 181,
  "start_ms": 100,
  "end_ms": 75291
}
```

## Response fields

| Field          | Description                                |
| -------------- | ------------------------------------------ |
| `object_id`    | Object that owns the returned chunks       |
| `vault_id`     | Vault containing the object                |
| `chunks`       | Full chunk entries for the requested range |
| `total_chunks` | Total stored chunk count for the object    |

Each chunk includes:

| Field                                | Description                                                                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `index`                              | Chunk index within the document                                                                                                                  |
| `text`                               | Full text of the chunk                                                                                                                           |
| `page_start`, `page_end`             | PDF page span when available                                                                                                                     |
| `word_start_index`, `word_end_index` | Word range when available                                                                                                                        |
| `start_ms`, `end_ms`                 | Source media timestamps for the first and last word in the chunk, in milliseconds, when the object is a media-backed transcript with real timing |

## Notes

* `end` is clamped to the document’s final chunk if you request past the end.
* Requests where `start` is out of range return an error.
* Objects without stored chunks return `total_chunks: 0` and an empty `chunks` array.
* `start_ms` and `end_ms` are omitted for normal documents and text-only transcripts. They are not inferred when media word timing is unavailable.