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

# List Documents - v3

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

List the documents in a collection (v3 parity with GET /v2/collections/\{name}/documents). With `metadata_filter`, one call maps an identifier from your own system to the Captain document, using the same filter grammar as query; pass `include_custom_metadata=true` to include each document's `custom_metadata`.

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

## Request

### Path parameters

- `collection_name` (string, required)

### Query parameters

- `limit` (integer, optional, default: 100)
- `offset` (integer, optional, default: 0)
- `include_custom_metadata` (boolean, optional, default: false) — Include each document's custom_metadata. Default false: a page can return up to 1000 documents and each metadata object can be up to 64 KB, so this is opt-in rather than riding along by default.
- `metadata_filter` (string, optional, nullable) — JSON filter over custom\_metadata, using the SAME grammar as query filters ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$exists/$and/$or, implicit $eq). Reverse lookup: which Captain document carries your ID, e.g. \{"payna\_file\_id": "doc\_18842"}.

## Response

### 200

Successful Response

- `collection_name` (string, required)
- `documents` (list of DocumentListItemV3, required)
- `limit` (integer, required)
- `offset` (integer, required)
- `total_count` (integer, required)

## Types

### DocumentListItemV3

One document in the v3 list-documents response (mirrors the v2 list item).

- `document_id` (string, required)
- `filename` (string, required)
- `chunk_count` (integer, optional, default: 0)
- `content_type` (string, optional, nullable)
- `created_at` (string, optional, nullable)
- `custom_metadata` (map from string to any, optional, nullable)
- `indexed_at` (string, optional, nullable)
- `indexing_status` (string, optional, nullable)
- `status` (string, optional, nullable)
- `uri` (string, optional, nullable)
- `checksum` (string, optional, nullable) — Checksum of the source bytes the current version was indexed from, prefixed with its algorithm (for example etag:...). Null when not recorded.
- `source_version_id` (string, optional, nullable) — The storage provider's object version the current version was indexed from, when the provider reports one.

## Examples

**Response**

```json
{
  "collection_name": "my_documents",
  "documents": [
    {
      "document_id": "b3f9a1c2d4e5f60718293a4b5c6d7e8f",
      "filename": "loan-packet.pdf",
      "chunk_count": 42,
      "content_type": "application/pdf",
      "created_at": "2026-08-20T02:15:11.000000",
      "custom_metadata": {
        "external_id": "doc_18842",
        "client": "acme-lending"
      },
      "indexed_at": "2026-08-20T02:15:42.000000+00:00",
      "indexing_status": "completed",
      "status": "ready",
      "uri": "captain://org_123/users/shared/collections/my_documents/loan-packet.pdf"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total_count": 1
}
```

**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 = {
    # same filter grammar as query: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or
    "metadata_filter": json.dumps({"external_id": {"$eq": "doc_18842"}}),
    "include_custom_metadata": True,
}

response = requests.get(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/documents",
    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 params = new URLSearchParams({
  metadata_filter: JSON.stringify({ external_id: { $eq: "doc_18842" } }),
  include_custom_metadata: "true",
});

const response = await fetch(
  `${BASE_URL}/v3/collections/${collection_name}/documents?${params}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } },
);

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