Paginate and Filter CVM Documents via API

The problem

Brazilian issuers file many PDFs per year. FRE packages alone can return dozens of section files. Without filters you page through noise; without pagination you hit perPage validation errors or blow your request budget. Product code needs stable query parameters, not ad-hoc CSV joins.

Filter parameters

Combine filters liberally. Typical product query: ticker + type + year.

Pagination

Exceeding perPage=50 returns 422 validation errors. Loop pages until data is empty or shorter than perPage.

Example: curl — DFP for PETR4

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=20&page=1"

Multiple types in one call

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&types=DFP,ITR&year=2024&perPage=50"

Narrow FRE by name

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FRE&year=2025&name=DescricaoFatoresRisco&perPage=5"

Example: Python — walk all pages

import os, requests

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}

def list_all(**params):
    page, out = 1, []
    while True:
        r = requests.get(
            f"{BASE}/v1/documents",
            headers=H,
            params={**params, "page": page, "perPage": 50},
        )
        r.raise_for_status()
        batch = r.json()["data"]
        out.extend(batch)
        if len(batch) < 50:
            break
        page += 1
    return out

docs = list_all(ticker="PETR4", type="ITR", year=2024)
print(len(docs), "ITR files")
for d in docs[:3]:
    print(d["id"], d["name"], d["dateRef"])

Each item includes id, type, year, dateRef, name, and nested company with tickers — enough to choose a file before GET /v1/documents/:id/file.

Choosing filters for common jobs

FRE years often return many section PDFs. Prefer name filters (for example risk factors) instead of downloading every page of every file. See also filter by section name.

Validation errors on pagination

perPage outside 1–50 returns 422 with VALIDATION_FAILED and field messages in error.details. Fix the client — do not retry the same invalid value.

# Bad: perPage=100 → 422
curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=100"

From list → file → text

Filtering only returns metadata. Next steps:

1. Pick document.id from data[]
2. GET /v1/documents/:id if you need a single metadata refresh
3. GET /v1/documents/:id/file for the original PDF
4. POST /v1/document-text-extractions when you need page markdown (async callback)

Keep list queries cheap (perPage just large enough) so watchlist jobs stay inside the rate limit window.

Current limitations

• perPage maximum is 50.
• Coverage is the ingested corpus (primarily DFP, ITR, FRE), not every CVM portal category.
• Filtering by name is partial-match on stored document names; naming conventions vary by issuer.
• types accepts comma-separated values; unknown types simply yield empty data for that slice of the corpus.

Next steps

• Read the API docs
• Get an API key
• Download DFP and ITR filings
• DFP filing type

Related guides

• Getting started with the CVM filings API
• CVM API authentication
• Filter CVM filings by section name