Home / Earnings

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:

python
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/:

python
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.

python
[{'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:

python
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.

python
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:

python
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.

viewYou getGood 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_dateThe 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_periodEverything one release reported, comparatives included.What a bank said in a given quarter.
first_publishedEach data point's value as first published.Measuring restatements against time_series.
allEvery 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:

python
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:

python
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).

python
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:

python
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

StatusMeaning
401Missing, 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.

What's next?