> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# Get Chunks

GET https://api.filesearch.dev/v3/collections/{collection_name}/chunks

List chunks for a document with pagination and optional regions or metadata.

Reference: https://docs.filesearch.dev/reference/v3/documents/chunks

## Request

### Path parameters

- `collection_name` (string, required)

### Query parameters

- `document_id` (string, required)
- `limit` (integer, optional, default: 100)
- `cursor` (integer, optional, default: 0)
- `include_regions` (boolean, optional, default: false)
- `include_metadata` (boolean, optional, default: true)

## Response

### 200

List Chunks response.

- `collection_name` (string, required)
- `document_id` (string, required)
- `total_results` (integer, required)
- `limit` (integer, required)
- `chunks` (list of DocumentChunkV3, optional)
- `cursor` (integer, optional, default: 0)
- `next_cursor` (integer, optional, nullable)
- `warnings` (list of string, optional)

## Errors

### 401 Unauthorized Error

Missing or invalid authentication.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 403 Forbidden Error

Collection is inactive.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 404 Not Found Error

Collection not found.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

## Types

### DocumentChunkV3

- `chunk_id` (string, required)
- `document_id` (string, required)
- `text` (string, required)
- `location` (FileSearchLocationFromV3, optional, nullable)
- `regions` (list of FileSearchRegionFromV3, optional, nullable)
- `custom_metadata` (DocumentChunkV3CustomMetadata, optional, nullable)
- `metadata` (DocumentChunkV3Metadata, optional, nullable)
- `chunk_type` (enum, optional, nullable) — Layout role of this chunk, classified from the parser's block structure at indexing time: body, table, heading, page_header, page_footer, footnote, or figure. Null when the chunk has no label: content indexed before chunk types shipped, plain-text and media content, or regions the parser returned without block structure. Treat unknown future values as additive.
  - Allowed values: `body`, `table`, `heading`, `page_header`, `page_footer`, `footnote`, `figure`

### FileSearchLocationFromV3

- `page_start` (integer, optional, nullable)
- `page_end` (integer, optional, nullable)
- `chunk_index` (integer, optional, nullable)
- `parent_chunk_index` (integer, optional, nullable)
- `start_seconds` (double, optional, nullable)
- `end_seconds` (double, optional, nullable)
- `sheet_name` (string, optional, nullable)
- `row_start` (integer, optional, nullable)
- `row_end` (integer, optional, nullable)
- `col_start` (integer, optional, nullable)
- `col_end` (integer, optional, nullable)

### FileSearchRegionFromV3

- `type` (string, optional, nullable) — Region category, such as `text`, `title`, `section_header`, `key_value`, `table`, `figure`, `chart`, or `image`. Regions of type `figure`, `chart`, or `image` also carry a cropped `image_url` (a visual citation).
- `text` (string, optional, nullable)
- `page` (integer, optional, nullable)
- `bbox` (map from string to double, optional, nullable)
- `confidence` (string, optional, nullable)
- `image_url` (string, optional, nullable) — Short-lived presigned URL to a cropped image of the region (a visual citation), returned for `figure`, `chart`, and `image` regions when `include.regions` is true. Null for text regions and for documents indexed before figure cropping was enabled. Fetch promptly — the link expires within minutes.
- `description` (string, optional, nullable)

### DocumentChunkV3CustomMetadata

### DocumentChunkV3Metadata

## Examples

**Response**

```json
{
  "collection_name": "research_library",
  "document_id": "doc_climate_agriculture_2024",
  "total_results": 42,
  "limit": 2,
  "chunks": [
    {
      "chunk_id": "chunk_agri_report_001",
      "document_id": "doc_climate_agriculture_2024",
      "text": "Recent studies show that climate change affects crop yields through heat stress, shifting precipitation, and more frequent extreme weather events.",
      "location": {
        "page_start": 12,
        "page_end": 13,
        "chunk_index": 4,
        "parent_chunk_index": 1
      },
      "regions": [
        {
          "type": "text",
          "text": "Projected maize yield declines under high temperature scenarios",
          "page": 12,
          "bbox": {
            "x": 0.18,
            "y": 0.24,
            "width": 0.62,
            "height": 0.08
          },
          "confidence": "high"
        },
        {
          "type": "chart",
          "page": 13,
          "bbox": {
            "x": 0.12,
            "y": 0.31,
            "width": 0.76,
            "height": 0.42
          },
          "confidence": "medium",
          "image_url": "https://storage.example.com/previews/climate-agriculture-chart-p13.png",
          "description": "Chart comparing projected crop yield changes by region."
        }
      ],
      "custom_metadata": {
        "review_status": "peer_reviewed",
        "topic": "agriculture"
      },
      "metadata": {
        "section": "Projected yield impacts",
        "page_count": 2
      }
    },
    {
      "chunk_id": "chunk_agri_report_002",
      "document_id": "doc_climate_agriculture_2024",
      "text": "Adaptation measures include drought resistant seed varieties, improved irrigation scheduling, and soil moisture monitoring.",
      "location": {
        "page_start": 14,
        "page_end": 14,
        "chunk_index": 5,
        "parent_chunk_index": 1
      },
      "regions": [
        {
          "type": "text",
          "text": "Adaptation measures include drought resistant seed varieties",
          "page": 14,
          "bbox": {
            "x": 0.16,
            "y": 0.19,
            "width": 0.68,
            "height": 0.06
          },
          "confidence": "high"
        }
      ],
      "custom_metadata": {
        "review_status": "peer_reviewed",
        "topic": "adaptation"
      },
      "metadata": {
        "section": "Adaptation strategies"
      }
    }
  ],
  "cursor": 0,
  "next_cursor": 2,
  "warnings": []
}
```

**SDK Code**

```python
import json
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

params = {
    "document_id": "example_document_id",
    "limit": 10,
    "cursor": 0,
    "include_regions": False,
    "include_metadata": True
}

response = requests.get(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/chunks",
    headers=headers,
    params=params,
    timeout=30.0
)

print(json.dumps(response.json(), indent=2))
```

```typescript
const BASE_URL = "https://api.filesearch.dev";

const API_KEY = "your_api_key";

const collection_name = "my_documents";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
};

const params = new URLSearchParams({
  "document_id": "example_document_id",
  "limit": "10",
  "cursor": "0",
  "include_regions": "false",
  "include_metadata": "true"
});

const response = await fetch(`${BASE_URL}/v3/collections/${collection_name}/chunks?${params}`, {
  method: "GET",
  headers,
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));
```