Getting started with the earnings endpoint
The earnings endpoint gives you access to structured P&L, balance sheet, KPI and key-metrics figures pulled from banks' own earnings releases: the bank's data pack, or its PDF report where the data pack doesn't carry a figure. This is a different source from /v1/p3dh-data/ and /v1/metrics/. Those are built from the EBA Pillar 3 Hub and follow a standardized format. Earnings supplements are self-reported by the bank, published on its own timeline, and not cross-validated against the P3DH figures. Reach for /v1/earnings/ when you want a bank's own framing of its results, such as segment detail, KPI definitions, or history the bank itself chose to disclose, rather than the regulator's standardised template. Another reason to reach for /v1/earnings/ is the much shorter publication lag or earnings releases than that of Pillar 3 reports.
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/earnings/",
headers={"X-API-Key": API_KEY},
params={"entity_lei": "7LTWFZYICNSX8D621K86.CON", "category": "pnl"},
)Example
Let's say you're looking for Deutsche Bank's net interest income over time. Resolve its entity_lei from /v1/banks/ (the same LEIs used across every endpoint in this API), then request the line item from /v1/earnings/:
url = API_URL + "v1/earnings/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"entity_lei": "7LTWFZYICNSX8D621K86.CON", # Deutsche Bank AG
"schema_item": "Net interest income",
},
)
data.json()The API returns JSON in long format: one row per bank, line item and period.
[{'row_id': 'd6d8d2d473ced199',
'entity_lei': '7LTWFZYICNSX8D621K86.CON',
'short_name': 'Deutsche Bank',
'abbreviation': 'DBK',
'slug': 'DBK',
'bank_id': 'deutsche',
'bank_name': 'Deutsche Bank AG',
'category': 'pnl',
'section': 'pnl',
'schema_item': 'Net interest income',
'period': '2024-FY',
'period_end_date': '2024-12-31',
'value': 13065.42443919,
'unit': 'millions',
'currency': 'EUR',
'value_type': 'reported',
'reporting_basis': 'reported',
'publication_period': '2026-Q2',
'publication_date': '2026-07-29',
'source': 'deutsche_financial_data_supplement',
'source_file': 'data/deutsche/2026-Q2/data_packs/FDS-Q2-2026-29072026.xlsb',
'source_file_name': 'FDS-Q2-2026-29072026.xlsb',
'sheet': 'ConsIncome',
'source_page': None,
'source_text': 'Net interest income',
'basis_match': 'exact',
'note': None,
'data_quality_score': 'high',
'human_verification': False,
'date_stamped_view': True,
'time_series_view': True,
'creation_date': '2026-11-09T21:07:14'},
...]Note: schema_item is a consistent name across all banks; source_text is what the bank itself printed, the row label in its data pack or the quoted line of its PDF. Use schema_item to compare banks, and source_file, sheet, source_page and source_text to trace a number back to its source. value is in unit (here millions of currency); ratios come as fractions, so 0.123 means 12.3%.
In Python, this transforms easily into wide format with pandas:
import pandas as pd
df = pd.DataFrame(data.json())
wide = df.pivot(index="period", columns="bank_name", values="value")Dimensions
Every earnings record sits at the intersection of a bank, a period, and a line item.
Banks
entity_lei is the same identifier used across /v1/banks/, /v1/p3dh-data/, and /v1/metrics/. Look one up in the banks dictionary. bank_name is also on every record, but it's the bank's name as in its own publications, which can differ slightly in formatting from the canonical entity_name on /v1/banks/ (e.g. "UniCredit S.p.A." here vs. "UNICREDIT, SOCIETA' PER AZIONI" there). Join on entity_lei, not on name, whenever you're combining earnings data with another endpoint.
Periods
period is the fiscal period a value is reported for: "2014-Q4", "2024-FY", "2016-6M", or "2016-9M" (calendar-year fiscal year), not an ISO date. Note that some banks report year-to-date totals, especially for P&L items, which are signified using 6M, 9M, FY. period_end_date is the same period expressed as a date, useful for sorting or filtering with >=/<= logic client-side. publication_period is a different thing: the quarter of the *publication* the value comes from, e.g. "2025-Q3", and publication_date the day it came out. A publication restates comparatives for earlier periods alongside its own quarter, so period and publication_period often differ. See Restatements and views.
url = API_URL + "v1/earnings/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"entity_lei": "K8MS7FD7N5Z2WQ51AZ71.CON", # BBVA
"schema_item": "CET1 ratio",
"period": ["2023-Q4", "2024-Q4"],
},
)Line items
schema_item is a normalised name, comparable across banks and publications. Pass it to /v1/earnings/ directly, or browse the full catalog first at /v1/metadata-earnings/ (the earnings dictionary is the same catalog as a searchable page, with each item's unit). category (pnl, asset, equity_liability, kpi, km12) and section (pnl, assets, liabilities, equity, kpi, capital, ...) are broader groupings, useful for pulling a whole statement at once:
url = API_URL + "v1/earnings/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"entity_lei": "K8MS7FD7N5Z2WQ51AZ71.CON", # BBVA
"category": "asset",
"period": "2024-Q4",
},
)reporting_basis distinguishes reported figures from underlying/pro forma ones where a bank discloses both. Most rows are reported. value_type is derived for the few figures not printed as such but computed from the publication's own parts (the formula is in note), and basis_match is partial when the bank's line doesn't exactly match the item's definition (note says why).
Restatements and views
Every publication prints its own quarter and restates comparatives for earlier ones, so one data point (a bank, line item and period) usually has a value in several publications, and sometimes the value changes. The view parameter decides which of those values you get. All other filters work the same in every view.
view | You get | Good for |
|---|---|---|
time_series (default) | The newest value of each data point, the latest restated figure. | Comparable history. Note the look-ahead: a 2020 figure may come from a 2022 publication. |
as_of + as_of_date | The data as it stood on that day: per data point, the value from the latest publication already out. | Backtests, free of look-ahead. |
release + publication_period | Everything one release reported, comparatives included. | What a bank said in a given quarter. |
first_published | Each data point's value as first published. | Measuring restatements against time_series. |
all | Every value of every publication. | Audits. |
Deutsche Bank's total assets for 2020-Q4 as the market knew them in March 2021, and as they stand today:
url = API_URL + "v1/earnings/"
params = {
"entity_lei": "7LTWFZYICNSX8D621K86.CON",
"schema_item": "Total assets",
"period": "2020-Q4",
}
then = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={**params, "view": "as_of", "as_of_date": "2021-03-31"},
)
now = requests.get(url=url, headers={"X-API-Key": API_KEY}, params=params)date_stamped_view and time_series_view on each record are the flags these views are built on; with view=all you can apply them yourself.
Refreshing panels
Most recurrent analytical workflows need a set of line items for a set of banks across every available period: a panel. This is the same /v1/earnings/ call, just without a period filter:
url = API_URL + "v1/earnings/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY},
params={
"schema_item": "CET1 ratio",
"category": "km12",
"entity_lei": ["7LTWFZYICNSX8D621K86.CON", "K8MS7FD7N5Z2WQ51AZ71.CON"],
},
)
panel = pd.DataFrame(data.json()).pivot(
index="period_end_date", columns="bank_name", values="value"
)Offsets and pagination
/v1/earnings/ defaults to limit=1000, capped at your key's per-request maximum. Page through a larger result with offset, and check X-Has-More to know when to stop: the same header contract as /v1/p3dh-data/ and /v1/metrics/ (X-Result-Count, X-Has-More, X-Limit, X-Offset, X-Plan-Capped).
url = API_URL + "v1/earnings/"
data = requests.get(
url=url,
headers={"X-API-Key": API_KEY}, # the API key only
params={
"category": "pnl",
"limit": 1000, # rows per page
"offset": 1000, # rows to skip: this is the second page
},
)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, not a page number: the second page of 1,000 rows starts at offset=1000, not offset=1.
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/earnings/"
headers = {"X-API-Key": API_KEY}
params = {"category": "pnl", "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)Some keys are also restricted to the previous calendar year onward (period_end_date, server-side). Call GET /v1/me/ to check your own key's limits.
Error handling
| Status | Meaning |
|---|---|
401 | Missing, unrecognized, or revoked API key. |
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.