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

# bigdata_list_documents

> Paginated, filterable list of private document metadata for corpus navigation.

## Overview

List Private Documents returns a paginated, filterable list of document **metadata** from the private corpus. Use it to see what documents exist — by connector, origin, tags, date, or file name — before reading or searching content.

## When to Use

List Private Documents is ideal for:

* **Recent uploads:** Checking what was added yesterday, this week, or since a given date
* **Connector browsing:** Listing the latest files from a specific email, broker research, or SharePoint connector
* **Tag-based inventory:** Finding documents that carry broker, sender, recipient, or custom tags
* **Id resolution:** Locating a `document_id` to pass to [`bigdata_fetch_document`](/mcp-reference/tools/bigdata-fetch-document)

<Tip>
  This tool returns metadata for navigation. For relevance-ranked content retrieval, use [`bigdata_search`](/mcp-reference/tools/bigdata-search). To read one document end-to-end, use [`bigdata_fetch_document`](/mcp-reference/tools/bigdata-fetch-document).
</Tip>

## How It Works

1. Optionally resolve a `connector_id` with [`bigdata_list_connectors`](/mcp-reference/tools/bigdata-list-connectors)
2. Optionally confirm tags with [`bigdata_list_tags`](/mcp-reference/tools/bigdata-list-tags)
3. Call `bigdata_list_documents` with the relevant filters and pagination
4. Use returned ids to fetch full text or follow up with search

## Parameters

| Parameter    | Type      | Required | Description                                                                                                                                                                                                                               |
| ------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origin`     | enum      | No       | Restrict to a single ingestion source: `email`, `investment_research`, `file_upload`, or `sharepoint`.                                                                                                                                    |
| `connector`  | string    | No       | Restrict to documents from a specific connector. Pass the `connector_id` from `bigdata_list_connectors`.                                                                                                                                  |
| `tags`       | string\[] | No       | Filter by tag names — **OR** logic (documents matching any of the given tags). Supports auto-tags such as `broker:Goldman Sachs`, `from:analyst@example.com`, `to:you@example.com`, `label:Legal`, and custom tags such as `topic:macro`. |
| `file_name`  | string    | No       | Case-insensitive partial match on file name.                                                                                                                                                                                              |
| `from_date`  | string    | No       | ISO 8601 timestamp. Include only documents created on or after this date.                                                                                                                                                                 |
| `sort_by`    | enum      | No       | `created_at` (default), `updated_at`, `file_name`, `raw_size`, `content_type`, or `status`.                                                                                                                                               |
| `sort_order` | enum      | No       | `asc` or `desc`. Default `desc` (newest first with `created_at`).                                                                                                                                                                         |
| `page`       | integer   | No       | 1-based page number. Default `1`.                                                                                                                                                                                                         |
| `page_size`  | integer   | No       | Results per page. Default `50`.                                                                                                                                                                                                           |

### Important Notes

* Combine `connector` and `tags` to narrow results within a single source (for example, emails from a specific sender)
* A full page of results usually means more pages are available — advance `page` to continue
* File management actions such as rename, delete, sharing changes, or uploading originals of any type or size are handled at [https://app.bigdata.com/files](https://app.bigdata.com/files)

## Data Returned

An array of document summaries. Each includes:

| Field                                        | Description                       |
| -------------------------------------------- | --------------------------------- |
| `id`                                         | Document id for fetch             |
| `file_name`                                  | Display file name                 |
| `request_origin`                             | Ingestion origin                  |
| `content_type`                               | Content type                      |
| `status`                                     | Processing status                 |
| `connector_id`                               | Source connector, when applicable |
| `tags`                                       | Array of `{id, name}`             |
| `raw_size`                                   | Size of the original file         |
| `shared_with_orgs`                           | Organisation sharing              |
| `created_at` / `updated_at` / `published_at` | Timestamps                        |
| `error_code`                                 | Present when processing failed    |

## Practical Tips

### Large result sets

Summarize before listing every row — for example, highlight the five most recent documents and offer to narrow by tag, date, or file name.

### Auto-tags

Surface notable auto-tags from each document's `tags` field (`broker:`, `from:`, `to:`, `label:`) to make corpus organisation clear when presenting results.

### Next steps

Once the right document is identified, use [`bigdata_fetch_document`](/mcp-reference/tools/bigdata-fetch-document) for the full text, or [`bigdata_search`](/mcp-reference/tools/bigdata-search) for relevance-ranked synthesis across multiple files.