Metadata is extra information you attach to a document when you upload it, written as a dict. The agent can then find documents by their metadata, without opening any of them. Try it in two parts:

1. Declare a folder’s fields and upload a filing with its metadata, with your own PageIndex API key.
2. Ask a library of 120 filings by metadata, with our read-only demo key.

Part 1 · Add metadata on upload

Set up

pip install -U pageindex

Part 1 creates a folder in your PageIndex Cloud library, so it uses your own API key . Declaring fields and uploading need no chat model:

import os
from pageindex import PageIndexClient
 
os.environ["PAGEINDEX_API_KEY"] = "Your PageIndex API key here"
 
client = PageIndexClient(index="cloud")

Declare the fields

A folder’s metadata schema lists the fields its documents can have. Each field has a type: string, number or boolean. A description is optional and tells the agent what the field means.

folder_id = client.create_folder("SEC Filings")["folder"]["id"]
 
client.create_metadata_schema(folder_id, {
    "company": {"type": "string"},
    "form_type": {"type": "string", "description": "10-K (annual report) or 10-Q (quarterly report)"},
})

For subfolders and changing a schema, see the metadata reference.

Add metadata on upload

Pass the document’s metadata to submit_document():

client.submit_document(
    "amd-20250628.pdf",
    folder_id=folder_id,
    metadata={"company": "AMD", "form_type": "10-Q"},
)

Use only the folder’s fields, each with its declared type.

Part 2 · Search a large library by metadata

A library of 120 filings with metadata is ready on PageIndex Cloud. It holds the annual and quarterly reports of six chip companies, NVIDIA, AMD, Intel, Broadcom, Qualcomm and Micron, over five years. Its files are named by ID number, so no file name tells you the company, the report type or the quarter.

Connect to the library

The demo client reads the library with our read-only demo key, and your OpenAI key answers:

os.environ["OPENAI_API_KEY"] = "Your OpenAI API key here"
 
demo = PageIndexClient(
    index={"api_key": "pageindex_demo_readonly_key"},
    chat="gpt-5.6-luna",
)
LIBRARY_ID = "cmvoxrjpy002l0dnql7m69wh9"  # the 120-filing library

Ask by metadata

Ask for the third-quarter reports from fiscal 2024 onward:

for chunk in demo.chat("List the third-quarter 10-Qs from fiscal 2024 onward, with each company and fiscal year.",
                       folder_id=LIBRARY_ID, stream=True):
    print(chunk, end="", flush=True)

[tool_call] get_metadata_schema {"folder_id": "cmvoxrjpy002l0dnql7m69wh9"}
[tool_call] search_documents {"mode": "metadata", "metadata": {"metadata_filter": {"form_type": "10-Q", "fiscal_quarter": 3, "fiscal_year": {"$gte": 2024}}}}

Third-quarter Form 10-Q filings from fiscal 2024 onward:

| Fiscal year | Company | Filing |
|---|---|---|
| 2024 | AMD | `0000002488-24-000163.pdf` |
| 2024 | Broadcom | `0001730168-24-000099.pdf` |
...
| 2026 | Micron | `0000723125-26-000015.pdf` |
| 2026 | NVIDIA | `0001045810-25-000230.pdf` |

There are 14 matching filings in the folder.

The agent first read the library’s fields. Then it searched for form_type 10-Q, fiscal_quarter 3 and fiscal_year 2024 or later ($gte means “greater than or equal to”).

Result

A filing carries its metadata from the moment it is uploaded. A library of 120 filings is searched by fields no file name holds, without opening any filing.

The notebook runs both parts with your keys: open it in Colab .