Getting started with the metrics endpoint
This API delivers structured and comparable metrics for a large number of European banks. It lets you build queries that return datasets meeting fixed dimension values, such as a key risk indicator across a fixed group of banks or one bank's full capital-adequacy picture over time.
The database powering the API endpoints is updated daily, ensuring synchronization with the EBA's Pillar 3 Data Hub. This makes the endpoints suited to risk monitoring and analytics workflows that need to reflect the latest published disclosures without you having to re-scrape anything yourself.
Authentication
All endpoints require authentication through an API key, included in the X-API-Key header. Set it alongside the API's base URL. Every example below builds on these two variables:
import requests
API_URL = "https://app-2b3bd7f4-0899-420d-be54-0a0cfb9b0879.cleverapps.io/"
API_KEY = "full_key_goes_here"
data = requests.get(
url=API_URL + "v1/metrics/",
headers={"X-API-Key": API_KEY},
params={"metric_name": "cet1_ratio"},
)Metrics
The API is organized around the concept of metrics. A metric is typically a ratio, like the leverage ratio or liquidity coverage ratio, computed from Pillar 3 disclosures. Nominal values can also be metrics, such as total leverage ratio exposure, or a CET1 capital amount itself.
You can search for metrics using the /v1/search/ endpoint, or browse the full catalog at /v1/metadata-metrics/. The metrics dictionary is the same catalog as a searchable page, useful when you'd rather browse than write a request.
Example
Let's say you're looking for the CET1 headroom of ING and BNP Paribas at year-end 2025. First, resolve each bank's entity_lei (see Dimension: banks below), then request the metric from /v1/metrics/. entity_lei is repeatable, so both banks come back in one call:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"entity_lei": [
"549300NYKK9MWM7GGW15.CON", # ING Groep N.V.
"R0MUWSFPU8MPRO8K5P83.CON", # BNP Paribas
],
"metric_name": "headroom_cet1",
"ref_period": "2025-12-31",
},
)
data.json()The API returns JSON in long format: one row per bank, period, and metric.
[{'entity_lei': '549300NYKK9MWM7GGW15.CON',
'entity_name': 'ING Groep N.V.',
'entity_type': 'Banking Group',
'institution_type': 'Large highest EEA',
'country': 'Netherlands',
'ref_period': '2025-12-31',
'category': 'capital_adequacy',
'metric_name': 'headroom_cet1',
'metric_label': 'CET1 headroom over the total SREP requirement and CBR',
'definition': 'The metric is computed as follows: [K 61.00 & c0010 & r0050] - [total_srep_cet1_requirement], which translates to [EU KM1 - Key metrics template | a. T | 5. Common Equity Tier 1 ratio (%)] - [Total SREP CET1 requirement incl. buffers]',
'transformation': 'none',
'value': 0.0193,
'unit': 'ratio'}]In Python, this transforms easily into wide format with pandas:
import pandas as pd
df = pd.DataFrame(data.json())
wide = df.pivot(index="entity_name", columns="ref_period", values="value")Dimensions
Every metric has three dimensions: it's associated with a bank, a reference period, and a category. You can filter on multiple dimensions at once, and the API accepts multiple values for the bank, category, and reference period dimensions in a single request.
Categories
Metrics are also organized into categories, allowing full retrieval of every metric in a category in one call:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={"category": "liquidity",
"entity_name": "ING Groep N.V.",
"ref_period": "2025-12-31"},
)
data.json()These categories are currently available:
asset_encumbranceasset_qualitycapital_adequacyclimateirrbbleverage_detailliquiditymrel_tlacrwa_composition
Four more come from banks' own earnings releases rather than their Pillar 3 filings (source_kind earnings or mixed in /v1/metadata-metrics/):
profitability— RoTE, RoE, net interest margin, cost/income, jaws, effective tax rate, and morebalance_sheet— cost of risk, loan-to-deposit ratio, customer loans and depositsshareholder_value— organic capital generation, CET1 headroom to the MDA trigger in EUR, tangible book value per share, EPSreported_kpis— each bank's own KPIs as it reports them, e.g.reported_rote, to set next to the computed one
Earnings releases also fill the latest quarters of some Pillar 3 metrics, such as cet1_ratio or lcr, until the filing arrives: those rows have source EARNINGS. See the API reference.
A few more categories (credit risk mitigation, IRB adoption/detail, market risk, standardised credit risk) are still going through the same calculation review the Pillar 3 categories above have already had, and aren't served yet. /v1/metadata-metrics/ (no category filter) is always the accurate, current list; a category/metric_name outside it returns an empty result rather than an error, so there's no need to hardcode this list in your own code.
Call /v1/metadata-metrics/?category=<name> to see every metric within a category before you query for values: its label, compiled formula (definition), unit_kind, and which available_transformations it supports.
Banks
You can use the search endpoint to find a bank by name, abbreviation, or LEI code. For example, if you're looking for a specific Sparkasse:
url = API_URL + "v1/search/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={"keyword": "sparkasse"},
)
data.json()It's also possible to use the /v1/banks/ endpoint to request the full set of banks, filter locally, and use the results to build a query against /v1/metrics/. Let's take the example of filtering for all German banks and retrieving their leverage ratio. The join between the two calls is each bank's entity_lei:
url = API_URL + "v1/banks/"
banks = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={"country": "Germany"},
).json()
german_leis = [bank["entity_lei"] for bank in banks]url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"metric_name": "leverage_ratio",
"entity_lei": german_leis,
},
)
data.json()The banks endpoint takes these filters. Only entity_name is a partial match; the rest are exact:
- Partial, case-insensitive:
entity_name. - Exact:
entity_lei,entity_type,institution_type,country,size,systemic_relevance,ssm,stoxx. - Numeric range, in EUR billions:
min_exposure_bn/max_exposure_bn.
See the Banks section of the API reference guide for what each one accepts.
The banks dictionary is the same list as a searchable page. It's a quicker way to look up one bank's entity_lei than making a request for it.
Reference periods
Reference periods are quarter-end dates. Call /v1/periods/ to see the exact set your key can reach:
url = API_URL + "v1/periods/"
data = requests.get(url=url, headers={"X-API-Key": API_KEY})
data.json()Note that the reference periods will grow over time, as more historical data is added to the dataset.
Transformations
Each metric is associated with a number of transformations, which let you retrieve quarter-over-quarter and year-over-year changes of the original metric, computed from the same bank's value for the exact prior quarter or year (a skipped filing gives null, never a wider comparison):
none: no transformation is applied; the value as computed. The default.delta_qoq: absolute change from the previous quarter, in the same unit as the metric.delta_yoy: absolute change from the same quarter a year earlier.growth_qoq: quarter-over-quarter percentage change, always a dimensionless ratio regardless of the base metric's own unit.growth_yoy: year-over-year percentage change.
Boolean metrics only ever support none, as a delta or growth rate of a 0/1 flag isn't a meaningful figure. Check available_transformations on /v1/metadata-metrics/ for a given metric before requesting one of the other four.
Let's get the QoQ change in risk-weighted assets for Deutsche Bank:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"metric_name": "rwa_total",
"entity_name": "deutsche bank",
"transformation": "delta_qoq",
},
)Or the absolute change in the CET1 ratio over the last year for ING:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"metric_name": "cet1_ratio",
"entity_lei": "549300NYKK9MWM7GGW15.CON", # ING Groep N.V.
"transformation": "delta_yoy",
},
)Other dimensions
entity_type:Banking Group,CRD Credit Institution, orPILLAR3 Sub Group.institution_type:Large highest EEA,Other highest EEA, orLarge subsidiaries.metric_label: partial, multi-word match against a metric's human-readable label (e.g.metric_label=leverage+ratio), for when you know roughly what a metric is called but not its exactmetric_name.
Refreshing panels
Most recurrent analytical workflows require retrieving a set of metrics for a set of banks, across all available time periods: a panel. This is the same /v1/metrics/ call, just without a ref_period filter:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"metric_name": "cet1_ratio",
"entity_lei": ["549300NYKK9MWM7GGW15.CON", "7LTWFZYICNSX8D621K86.CON"],
},
)
data.json()And returns one row per bank per period, value always rounded to 4 decimal places (the stored figure keeps full precision; only the response is rounded):
[
{"entity_name": "ING Groep N.V.", "ref_period": "2025-06-30", "value": 0.1326, "unit": "ratio"},
{"entity_name": "ING Groep N.V.", "ref_period": "2025-09-30", "value": 0.1336, "unit": "ratio"},
{"entity_name": "DEUTSCHE BANK AKTIENGESELLSCHAFT", "ref_period": "2025-06-30", "value": 0.1424, "unit": "ratio"},
{"entity_name": "DEUTSCHE BANK AKTIENGESELLSCHAFT", "ref_period": "2025-09-30", "value": 0.145, "unit": "ratio"}
]This is most easily cast as a wide panel dataset, one row per period and one column per bank, ready for use in a time series chart or a regression:
panel = pd.DataFrame(data.json()).pivot(
index="ref_period", columns="entity_name", values="value"
)Handling null values
A metric's underlying value is not always available, usually because a bank does not report one of the data points needed to compute it. That's often a genuine gap, not an error: a module the bank doesn't file, a business it doesn't run, a quarter not yet published. For many metrics that's the majority of rows, so /v1/metrics/ excludes them by default: a plain call only returns rows where value is not null.
Pass include_null_values=true to get the unresolved rows back. This is useful when you're auditing coverage for one metric across banks, rather than pulling values to use directly:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={"metric_name": "leverage_ratio_ex_temp_exemptions", "include_null_values": True},
)Restatements are deduplicated by default: if a bank re-files the module a metric is computed from, only_latest (true by default) keeps only the row from the most-recently-submitted module for that (entity_lei, ref_period, metric_name, transformation) combination. Pass only_latest=false to get every submission's row back instead and decide for yourself which one you want. Filter on entity_lei and ref_period together, since the API won't pick one for you at that point.
Offsets and pagination
/v1/metrics/ returns at most limit rows per request. The default is limit=1000, and the server caps it at your key's per-request maximum. To fetch a larger result, request it one page at a time with offset.
limit and offset are query parameters, so they go in params, next to your filters. Only the API key goes in headers. The API doesn't read limit or offset from a header. If you put them there, you won't get an error, just the default first page (limit=1000, offset=0) on every call.
offset is the number of rows to skip. It isn't a page number. The second page of 1,000 rows starts at offset=1000, not offset=1.
Let's say you want every capital-adequacy, leverage and liquidity ratio for all banks at mid-year 2026. That's more than 1,000 rows, so request the second page like this:
url = API_URL + "v1/metrics/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY}, # the API key only
params={
"metric_name": ["cet1_ratio", "headroom_cet1", "leverage_ratio", "lcr", "nsfr"],
"ref_period": "2026-06-30",
"limit": 1000, # rows per page
"offset": 1000, # rows to skip: this is the second page
},
)Each response reports the pagination the server actually applied in its headers:
X-Result-Count: rows in this response.X-Has-More:trueif more rows are available after this page.X-Limit/X-Offset: the limit and offset that were applied.X-Limitcan be lower than thelimityou asked for if your key caps it.X-Plan-Capped:truewhen your key's cap, not your ownlimit, set the page size.
To check that your limit and offset were applied, compare them with X-Limit and X-Offset. These are the same headers /v1/p3dh-data/ and /v1/earnings/ return.
To fetch the whole result, loop until X-Has-More is false. Advance offset by X-Limit, not by the limit you asked for. If your key clamps a limit=5000 down to 1,000 and you advance by 5,000, you skip 4,000 rows each time and nothing tells you:
import pandas as pd
url = API_URL + "v1/metrics/"
headers = {"X-API-Key": API_KEY}
params = {
"metric_name": ["cet1_ratio", "headroom_cet1", "leverage_ratio", "lcr", "nsfr"],
"ref_period": "2026-06-30",
"limit": 1000,
"offset": 0,
}
pages = []
while True:
response = requests.get(url=url, headers=headers, params=params)
response.raise_for_status()
pages.append(pd.DataFrame(response.json()))
if response.headers["X-Has-More"] != "true":
break
params["offset"] += int(response.headers["X-Limit"])
df = pd.concat(pages, ignore_index=True)Each page counts as one request against your key's rate limits. On a key with a low daily quota, narrow the query with entity_lei, metric_name or category rather than paging through the full catalog.
Error handling
| Status | Meaning |
|---|---|
401 | Missing, unrecognized, or revoked API key. |
422 | An invalid parameter value, most often an unrecognized transformation. |
There's no 400 for exceeding your key's per-request row cap: limit is silently clamped instead, and X-Plan-Capped tells you it happened. Likewise there's no error for requesting data older than your key's history depth. It's just excluded from the response.