Skip to content

Searching SharePoint

Use the SharePoint search REST API to find sites, documents, people, and list items across the tenant. Queries use Keyword Query Language (KQL) with property filters, refiners, sort orders, suggestions, and pagination.

Prerequisites

Requirement Description Reference
Read access to the content being searched Search results respect item-level permissions. Users only see what they can access. SharePoint admin roles
Sites.ReadWrite.All Required for the admin examples SharePoint admin roles

How search works

flowchart LR
    Query["KQL Query\n(report.docx ContentType:document)"]
    SearchAPI["SharePoint Search\nREST API"]
    Results["Results\n(filtered by permissions)"]
    Refinement["Refiners /\nPagination"]

    Query --> SearchAPI
    SearchAPI --> Results
    SearchAPI --> Refinement
    Refinement --> Query

Search queries are sent to the /_api/search/query endpoint as KQL text. Results respect the requesting user's permissions.

Common KQL filters

Filter Example Description
IsDocument:1 project report IsDocument:1 Files only
contentclass:STS_Site contentclass:STS_Site Sites only
contentclass:SP.People contentclass:SP.People Smith People only
Path: Path:https://... Restrict scope
ContentType: ContentType:invoice Filter by content type
Author: Author:"Vadim G" Filter by author
LastModifiedTime: LastModifiedTime>2026-01-01 Date range

Examples

Query

Operation File Required role API reference
Keyword search query_keyword.py Read access to content Search REST API
Search documents (IsDocument) query_documents.py Read access to libraries Search REST API
Search sites (contentclass) query_sites.py Read access to sites Search REST API
Search people (contentclass) query_people.py Read access to people Search REST API
Search by site (Path:) query_by_site.py Read access to content Search REST API
Search by content type query_by_content_type.py Read access to content Search REST API
Filter by author / date range query_with_filter.py Read access to content Search REST API
Sort by managed property query_with_sort.py Read access to content Search REST API
Refinement / faceted drill-down query_with_refinement.py Read access to content Search REST API
Suggestions and auto-completion query_suggestions.py Read access to content Search REST API
Paginate through results query_paged.py Read access to content Search REST API
Export results to CSV export_results.py Read access to content Search REST API

Administration

Operation File Required role API reference
Crawl diagnostics, popular queries, suggestions admin/diagnostics.py Sites.ReadWrite.All Search REST API
Query configuration and promoted results admin/query_configuration.py Sites.ReadWrite.All Search REST API
Export search reports export_reports.py Search admin Search REST API

Quick start

from office365.sharepoint.client_context import ClientContext

ctx = ClientContext("https://contoso.sharepoint.com/sites/team").with_client_certificate(
    "contoso.onmicrosoft.com", client_id="client_id", thumbprint="thumbprint", cert_path="./cert.pem"
)

# Search for documents
result = ctx.search.post_query("IsDocument:1", row_limit=10).execute_query()
rows = result.value.PrimaryQueryResult.RelevantResults.Table.Rows
for row in rows:
    print(f"  {row.Cells['Path']}")

API reference