Fetch FRE Risk Factors Without Downloading the Full Filing

The problem

Risk review workflows hit three friction points:

1. Volume — FRE is filed in sections; risk disclosures alone may span multiple documents
2. Discovery — Section names follow CVM internal codes (DescricaoFatoresRisco-4_1), not human-readable labels in filenames
3. Extraction cost — Running markdown extraction on every FRE file when you only need risk chapters burns rate limits and callback volume

A FRE risk factors API workflow should resolve ticker → filter risk section names → download or extract only those documents.

FRE risk-related section names

CVM FRE templates split risk disclosures across several catalog entries. Common name prefixes:

Use partial matches — name=DescricaoFatoresRisco matches DescricaoFatoresRisco-4_1.

How apicvm helps

Step 1: List risk factor documents

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

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

Repeat for related sections:

for section in Descricao5PrincipaisFatoresRisco DescricaoRiscosMercado DescricaoGerenciamentoRiscos; do
  curl -s -H "Authorization: Bearer $APICVM_KEY" \
    "$APICVM_URL/v1/documents?ticker=VALE3&type=FRE&year=2024&name=$section&perPage=10" \
    | jq '.data[] | {id, name, dateRef}'
done

Step 2: Extract text from risk sections only

import os, requests

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
CALLBACK = "https://your-server.example/callbacks/apicvm"

RISK_SECTIONS = [
    "DescricaoFatoresRisco",
    "Descricao5PrincipaisFatoresRisco",
    "DescricaoRiscosMercado",
    "DescricaoGerenciamentoRiscos",
    "DescricaoControlesInternos",
]

def list_risk_docs(ticker: str, year: int) -> list[dict]:
    docs = []
    for section in RISK_SECTIONS:
        resp = requests.get(
            f"{BASE}/v1/documents",
            params={"ticker": ticker, "type": "FRE", "year": year, "name": section, "perPage": 10},
            headers=H,
        )
        resp.raise_for_status()
        docs.extend(resp.json()["data"])
    return docs

for doc in list_risk_docs("VALE3", 2024):
    requests.post(
        f"{BASE}/v1/document-text-extractions",
        json={"callback_url": CALLBACK, "document": {"id": doc["id"]}},
        headers=H,
    )
    print(f"Queued: {doc['name']}")

Page-level markdown arrives via callback — one POST per page with page.markdown content.

Step 3: Query risk themes

Once text is indexed, structure prompts or search around recurring themes:

• Commodity and FX — hedging policy, sensitivity disclosures
• Regulatory — environmental licensing, sector-specific rules
• Legal — cross-reference with contingency sections (separate FRE documents)
• Liquidity and leverage — covenant and refinancing risks
• Climate and ESG — often embedded in risk factor narratives

Cross-check risk narratives against DFP footnotes and ITR quarterly updates for financial quantification.

Example: PETR4 commodity and regulatory risks

Petrobras FRE risk sections typically cover oil price volatility, refining margins, divestiture programs, and environmental liabilities. A targeted query:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=PETR4&type=FRE&year=2024&name=DescricaoFatoresRisco"

Compare dateRef across results if multiple versions exist — FRE is updated periodically, not only at year-end.

Portfolio-scale risk monitoring

For a watchlist of tickers, loop resolve → list risk sections → queue extraction:

For each ticker in watchlist:
  1. GET /v1/documents?ticker={t}&type=FRE&year=2025&name=DescricaoFatoresRisco
  2. Store document IDs + names
  3. POST /v1/document-text-extractions for each
  4. Index markdown in vector store or keyword index
  5. Alert on new/changed risk language vs prior year

This avoids extracting governance, compensation, and shareholder sections you do not need for a risk-only product.

Current limitations

• Not a risk taxonomy API — apicvm returns documents and page markdown, not structured fields like risk_category or severity_score. Your pipeline classifies text.
• Section names are CVM codes — learn the prefix patterns; they are not localized English labels.
• Multiple files per theme — one logical "risk factors" section may map to several catalog documents.
• Corpus timing — documents reflect Hold ingestion; verify availability for your target year.
• Extraction is async — progress via callback only; Pro plan limits markdown extraction to 1 document per API key per UTC day.

Next steps

• Read the API docs
• Get an API key
• Filter any CVM section by name
• ESG and legal contingencies in FRE

Related guides

• Analyze governance and risk from FRE
• What is FRE — Formulário de Referência
• FRE filing type overview