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

# SharePoint Lists

> Query SharePoint lists as tables — every list on a site becomes a queryable table with typed columns and OData filters

Where the [SharePoint and OneDrive](https://docs.bow.ai/data-sources/connectors/sharepoint-onedrive.md) connector reads a site's **document libraries as files**, this connector reads the site's **SharePoint lists as tables**. Every list becomes a catalog table with typed columns, and the agent queries it the way it queries a database — filters, ordering and column selection run server-side through Microsoft Graph, and the rest happens in pandas.

> [!NOTE]
>
> The SharePoint Lists connector is part of the **Enterprise Edition**.

## What the agent sees

The connection points at one site. Every visible list on that site — a site can have many — is discovered as its own table:

* **Columns come from the list's own schema.** Text, choice, number, currency, date, boolean, person and lookup columns are typed accordingly; noise columns (compliance tags, attachments plumbing) are filtered out. `ID`, `Created`, `Modified`, `Created By` and `Modified By` are included.
* **Display names, not internal names.** A SharePoint column displayed as `2017` may internally be `field_2`; one displayed as `Category` may be `field_1`. The agent sees and filters on the display names it recognizes from the SharePoint UI — the connector translates to internal names on the wire and back in the results.
* **Document libraries and hidden system lists are excluded.** Libraries belong to the files connector; hidden lists can be opted back in with `include_hidden`.

Queries map 1:1 to Graph list-item calls with OData:

```json theme={null}
{"list": "2017_Expense_Data",
 "filter": "Category ne 'Total Expenses' and 2017 gt 1",
 "select": ["Category", "2017"],
 "orderby": "Modified desc",
 "limit": 1000}
```

The connector sends the `Prefer: HonorNonIndexedQueriesWarningMayFailRandomly` header so filters work on non-indexed columns, and follows `@odata.nextLink` paging up to the row cap.

## Before you start

The prerequisites are the same as for [SharePoint and OneDrive](https://docs.bow.ai/data-sources/connectors/sharepoint-onedrive.md): a **Microsoft Entra ID app registration** with a client secret, admin consent for the Graph permissions, and your BOW base URL for the OAuth redirect URI. If you already registered an app for the SharePoint files connector, **reuse it** — SharePoint Lists needs only `Sites.Read.All`, which that app already has.

| Access path | Graph permission needed |
| :- | :- |
| Per-user sign-in (recommended) | `Sites.Read.All` **delegated**, plus `User.Read`, `openid`, `profile`, `offline_access` |
| App-only catalog and queries | `Sites.Read.All` **application** permission with admin consent |

> [!NOTE]
>
> Unlike Graph *file* reads, Graph *list* reads work app-only on standard tenants — so a service-principal-only connection can index and query lists without any user signing in, as long as the application permission is granted. With delegated sign-in, each user sees exactly the lists and items their own account can see.

## Connect in BOW

Go to **Data Sources → Add data source** and pick **SharePoint Lists**.

### Config fields

| Field | Required | Default | Notes |
| :- | :- | :- | :- |
| `site_url` | Yes | — | Full site URL, e.g. `https://contoso.sharepoint.com/sites/Finance`. |
| `lists` | No | `*` | `*` exposes **all** qualifying lists on the site. Or a comma-separated set of list names to restrict the connection, e.g. `Expenses 2025, Vendors`. |
| `include_hidden` | No | `false` | Also expose lists SharePoint marks as hidden (site plumbing). Usually off. |
| `max_items` | No | `20000` | Safety cap on how many list items a single query may fetch. |

### Authentication modes

Identical to the SharePoint files connector, backed by the same Entra app registration:

* **Entra ID App (Service Principal)** — `tenant_id`, `client_id`, `client_secret` (with optional `oauth_client_id` / `oauth_client_secret` overrides). Backs both the app-only path and the per-user sign-in flow.
* **Sign in with Microsoft** — each user clicks **Connect** and completes the authorization-code flow; queries then run as that user. Entra SSO deployments also get OBO auto-provisioning, so users who log in with Microsoft are connected automatically.

See [Authentication and access](https://docs.bow.ai/data-sources/authentication.md) for shared vs per-user policies.

## Troubleshooting

> [accordion] A filter fails on a large list
>
> SharePoint rejects `$filter`/`$orderby` on non-indexed columns once a list crosses the 5,000-item view threshold, even with the Prefer header. Either index the column in SharePoint (List settings → Indexed columns), or drop the filter and let the agent filter in pandas — the connector's error message tells the agent to do exactly that.

> [accordion] A list is missing from the catalog
>
> Document libraries are excluded by design — use the SharePoint files connector for those. Hidden lists need `include_hidden`. If the connection has a `lists` scope, the list name must match one of the configured names.

> [accordion] The catalog is empty after connecting
>
> With a user-required connection and no `Sites.Read.All` application permission, the admin-side crawl legitimately finds nothing — the catalog populates per user after each user signs in with Microsoft.

> [accordion] A column is missing from a table
>
> Hidden and read-only system columns are filtered out of the catalog on purpose. Person and lookup columns return display values as strings.

## Related

* [SharePoint and OneDrive](https://docs.bow.ai/data-sources/connectors/sharepoint-onedrive.md) — the same site's document libraries, as files.
* [Business applications](https://docs.bow.ai/data-sources/connectors/business-apps.md) — other table-shaped application connectors (Salesforce, ServiceNow, NetSuite).
* [Authentication and access](https://docs.bow.ai/data-sources/authentication.md) — shared vs per-user credentials and OAuth.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.