From zero to your first call

Step 1: Get your API key

Create a free account, confirm the six-digit code we email you, then open Account settings, API tab and generate a key. The free tier includes API access, so you do not need a paid plan to start.

Name the key after where it will run rather than after yourself. When you hold two keys and need to rotate one, ci-pipeline tells you what breaks and my-key does not.

Put it in your environment rather than your source. Every example below reads it from there, so nothing on this page ever has your key written into it.

# macOS / Linux, add to ~/.zshrc or ~/.bashrc to persist
export BANKREG_API_TOKEN="brr_your_key_here"

# Windows PowerShell
$env:BANKREG_API_TOKEN = "brr_your_key_here"

Step 2: Install the SDK

The Python client wraps every endpoint and returns pandas DataFrames, so you can go from key to analysis without writing request plumbing.

pip install "bankregreports[pandas]"

# Without the pandas extra, methods return plain dicts and lists
pip install bankregreports

Not a Python shop? Every example has a plain HTTP equivalent, and the full schema is in the OpenAPI reference. Working in a spreadsheet instead? The same key signs in to the Excel add-in, which needs no code at all.

Step 3: Fetch your first data

The client reads BANKREG_API_TOKEN from the environment, so the constructor takes no arguments.

import bankregreports

brr = bankregreports.BankReg()

# One bank's latest snapshot. 852218 is JPMorgan Chase Bank, N.A.
df = brr.bank(852218)
print(df)

The same call over plain HTTP. Authentication is a bearer token on every request: no session, no OAuth dance, no token exchange.

curl "https://api.bankregreports.com/api/v1/banks/852218/" \
  -H "Authorization: Bearer $BANKREG_API_TOKEN"

Step 4: Build something with it

Screen the whole industry, then chart one bank against it. This is the shape of most real work on the API: a population query to find the interesting names, then a time series on the ones that matter.

import bankregreports
import matplotlib.pyplot as plt

brr = bankregreports.BankReg()

# 1. Every Georgia bank above $500M in assets
peers = brr.screener(state="GA", min_assets=500_000)
print(peers[["legal_name", "total_assets", "roa"]].head(10))

# 2. Twelve quarters of one bank's history
trend = brr.bank_trends(852218, quarters=12)

# 3. Plot it against the peer median
ax = trend.plot(x="report_date", y="roa", legend=False)
ax.axhline(peers["roa"].median(), linestyle="--")
ax.set_ylabel("Return on assets (%)")
plt.show()

Assets are in thousands of dollars, matching the source filings rather than silently rescaling them. A value that was not reported comes back as null, never as zero: treating a missing value as zero is how a ratio quietly becomes wrong.

Step 5: Know the edges

When something fails, the status code tells you what to do about it.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can pace a bulk job without guessing.

Rate limits and quotas

Limits apply to requests made with a brr_ key.

• Headers. RateLimit-Limit and RateLimit-Remaining describe the window shown in RateLimit-Policy (for example 1000;w=60). RateLimit-Reset is the number of seconds until that window frees up. On Pro and Scale the headers track the per-minute window, not the daily quota.
• Reset. The Pro and Scale daily quota resets at 00:00 UTC. The free allowance is a rolling 24-hour window, so capacity returns gradually.
• Over the limit. The request is refused with HTTP 429 and a Retry-After header giving the seconds to wait. There are no overage charges; nothing is billed past your plan.
• Excel add-in. The add-in calls this API with your key, so its requests count toward the same quota.
• MCP. Tool calls through the MCP server at https://api.bankregreports.com/api/mcp/ do not count toward your API quota. MCP has its own limits: without a key, 60 requests a minute and 200 tool calls a day per IP address; with a brr_ key, 300 requests a minute and 2,000 tool calls a day per account. MCP daily limits reset at 00:00 UTC.