filingrail 0.1.0

Python client for the Filingrail SEC EDGAR REST API on RapidAPI.

filingrail — Python client for the SEC EDGAR REST API

A thin, async-and-sync Python client for the Filingrail API on RapidAPI. Wraps the 7 v1 endpoints, returns typed dataclasses, no Pydantic dependency.

Install

Note: PyPI publication is pending. Watch the Filingrail RapidAPI listing — the live-on-PyPI announcement will land in the listing's About tab.

pip install filingrail  # PyPI publication pending

Get an API key

Subscribe on RapidAPI: https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail. Free tier = 50 calls/day, no card. Pro $9/mo for 5,000 calls.

Quickstart (sync)

from filingrail import FilingrailClient

with FilingrailClient(api_key="YOUR_X_RAPIDAPI_KEY") as client:
    # Resolve a ticker to its CIK
    [aapl] = client.search_companies("AAPL", limit=1)
    print(aapl.cik, aapl.name)  # 320193 Apple Inc.

    # Latest financials (balance sheet + income statement + cash flow)
    statements = client.get_financials("AAPL", limit=3)
    for s in statements:
        print(s.statement_type, s.period_end, s.line_items.get("total_assets"))

    # Recent insider trades
    trades = client.get_insider_trades("AAPL", limit=5)
    for t in trades:
        print(t.transaction_date, t.insider_name, t.shares, t.price_per_share)

    # Berkshire Hathaway's 13F holdings (CIK 1067983)
    holdings = client.get_13f_holdings(1067983, limit=10)
    for h in holdings:
        print(h.issuer_name, h.value_usd)

Quickstart (async)

import asyncio
from filingrail import AsyncFilingrailClient

async def main():
    async with AsyncFilingrailClient(api_key="YOUR_X_RAPIDAPI_KEY") as client:
        statements = await client.get_financials("MSFT")
        for s in statements:
            print(s.statement_type, s.period_end)

asyncio.run(main())

Environment variable

Set RAPIDAPI_KEY (or X_RAPIDAPI_KEY) and api_key becomes optional:

import os
os.environ["RAPIDAPI_KEY"] = "..."

from filingrail import FilingrailClient
client = FilingrailClient()

All endpoints

Method	Endpoint
search_companies(q, limit)	/v1/search/companies
get_recent_filings(form_type, cik, limit)	/v1/filings/recent
get_financials(ticker_or_cik, limit)	/v1/companies/{id}/financials
get_financials_history(ticker_or_cik, period, limit, statement_type, line_item)	/v1/companies/{id}/financials/history
get_insider_trades(ticker_or_cik, since, limit)	/v1/companies/{id}/insider-trades
get_8k_events(ticker_or_cik, since, limit)	/v1/companies/{id}/8k-events
get_13f_holdings(institution_cik, quarter, limit)	/v1/institutions/{cik}/13f-holdings
health()	/health

Errors

All non-2xx responses raise FilingrailError(message, status, detail). The detail is the parsed body when available, so you can pull out RapidAPI's specific error messages.

from filingrail import FilingrailClient, FilingrailError

try:
    client = FilingrailClient(api_key="wrong")
    client.search_companies("AAPL")
except FilingrailError as e:
    print(f"status={e.status} message={e}")

Why this exists

You could call httpx.get("https://filingrail.p.rapidapi.com/v1/...", headers=...) directly. The SDK saves you:

• typed responses (autocomplete in your IDE)
• no boilerplate for the RapidAPI auth headers
• consistent error handling
• example queries that match the canonical patterns documented in the RapidAPI listing's Docs tab

Links

• Filingrail homepage
• API docs (RapidAPI listing → Docs tab)
• Status page
• Issue tracker / source repo: TBD (public release pending — for now, email [e-mail])

License

MIT