Build a company KPI research workbook with Python and Excel

01 · SETUP

Set up your Python-to-Excel workflow

You’ll need Python 3.10 or newer. Save kpi_research_workbook.py in your working folder, then install the libraries:

python -m pip install requests openpyxl

Log in to get your API key. In the dashboard, click Create API key → Create key → Copy, then return here and replace YOUR_API_KEY below.

$env:VIZUALSTOCKS_API_KEY = "YOUR_API_KEY"

export VIZUALSTOCKS_API_KEY="YOUR_API_KEY"

Choose the command for your terminal. The key is sent in the X-API-Key header and is not saved in your research export.

02 · DISCOVER

Find the operating metrics your company actually reports

Start with Palantir. List the company-specific KPI IDs available for quarterly history:

python kpi_research_workbook.py --ticker PLTR --list-metrics

The Metric Catalog endpoint returns names, definitions, formats, status and frequency coverage. It lets you select operating measures rather than assume every company has a field called “ARR” or “customers.”

This example uses customerCount, netDollarRetention and remainingPerformanceObligations. They measure different things: a customer count, a cohort retention percentage and contracted commitments not yet recognized as revenue. They should not be summed or treated as interchangeable growth measures.

For another company, change the ticker, run discovery again and copy its returned metric IDs. Use the company list with hasCompanyKpis=true to discover covered tickers.

03 · WORKBOOK

Export company KPI history to Excel

python kpi_research_workbook.py --ticker PLTR --metrics customerCount netDollarRetention remainingPerformanceObligations --output pltr-kpi-research.xlsx

The script makes two read requests: one for definitions and one for All Company Metrics. It selects your metric columns and creates a new .xlsx file. The workbook has two sheets:

KPI history

Chronological observations with stable metric IDs as column headers. Normalized period, fiscal year, fiscal quarter and period end stay alongside the values. Filters and frozen headers make the table usable in a research model.

Metric definitions

The meaning, format, active/discontinued status and available coverage of each selected KPI, plus the API source and retrieval time. Review this sheet before comparing companies.

Open the file in Excel. Customer counts remain counts; RPO remains in the reporting currency’s base units. Percentage values use a literal percent suffix: a returned retention value of 157 displays as 157.0%, not 15,700%. Stored values are not scaled.

Rows where all selected KPIs are missing are omitted. Partial gaps stay blank—not zero and not forward-filled. This is a data workbook, not a valuation model or a forecast.

04 · SOURCES

Build a source-linked KPI table in Excel

When a number changes your research conclusion, you need to get back to the disclosure behind it. Add --include-sources to keep available document links beside each KPI observation:

python kpi_research_workbook.py --ticker PLTR --metrics customerCount netDollarRetention remainingPerformanceObligations --include-sources --output pltr-kpis-with-sources.xlsx

The original two sheets stay intact. A third, Source-linked data, gives you a filterable table with one row per non-missing KPI value: reporting period, metric ID, value, source coverage, original document, archived PDF, page number, source image and location notes.

1. Filter Metric ID to the KPI you are reviewing and select its reporting period.
2. Click Open PDF to open the returned archive at the cited page, where the PDF viewer supports page links. The page number is also recorded in the table.
3. Use Original source for the issuer’s document, or Source image for the returned page image. Compare the figure, units and reporting basis before using it in your model.

The request uses includeSources=true on All Company Metrics. The response’s sources array is joined on both normalizedPeriod and metricId within the same company and frequency—not on the company name or the latest document.

Source coverage can be partial. Not returned means the API did not supply a source reference for that observation; the value is kept without borrowing another period’s citation. Missing values stay blank on KPI history and do not get a source-table row. The export stores only returned web links, never your API key.

05 · CUSTOMIZE

Adapt the workbook to your research process

Request annual data directly

python kpi_research_workbook.py --ticker PLTR --frequency annual --metrics customerCount netDollarRetention --output pltr-annual-kpis.xlsx

Do not add quarterly customer counts or retention rates to invent annual values. These are not additive flows. Request the annual series and check its definition and coverage instead.

Build from a notebook

Keep the downloaded script beside your notebook. This example selects two KPIs and includes their source-linked table in a separate workbook:

from kpi_research_workbook import make_session, api_get, build_workbook

with make_session() as session:
    catalog = api_get(session, "/companies/PLTR/metrics/catalog",
                      type="companyKpi", status="all", frequency="quarterly")
    history = api_get(session, "/companies/PLTR/metrics",
                      type="companyKpi", status="all", frequency="quarterly", order="asc",
                      includeSources="true")

workbook, periods = build_workbook(
    history, catalog, ["customerCount", "netDollarRetention"], "quarterly", include_sources=True
)
with open("pltr-notebook.xlsx", "xb") as output:
    workbook.save(output)
print(f"Exported {periods} periods")

You can use openpyxl to add your own analysis on top of the returned workbook. Keep original source values separate from assumptions and calculations. The supplied export contains no macros, external workbook connections or embedded API key.

06 · REFRESH

Keep data refreshes separate from your working model

Rerun the command with a new filename after the next update, for example pltr-kpis-review-02.xlsx. The script refuses to overwrite an existing file, so it cannot erase notes or formulas you added in Excel.

Use fiscal year, fiscal quarter and period end when joining these observations to company statements. A normalized chart label is not always the issuer’s fiscal quarter. Keep annual and quarterly series separate and verify the reporting currency before comparing monetary KPIs.

A KPI may be redefined or discontinued. A catalog entry’s first and last available periods describe stored coverage, not a guarantee that every intervening value exists or the company used the same definition throughout. For a single series, see Retrieve Metric History.

07 · TROUBLESHOOTING

Resolve missing metrics or export errors

Metric unavailable

Run --list-metrics for the same ticker and frequency. IDs are company-specific and coverage depends on the key.

Blank cells

A blank means the selected metric has no value for that returned period. Do not replace it with zero to make a model balance.

401, 403 or 429

Check the key, data access and quota. The script retries temporary GET failures with backoff. See the error and rate-limit reference.

File exists or permission denied

Use a new .xlsx filename in a writable folder. Do not point the export at your working model.

Continue with revenue segmentation in Python. Python reference: openpyxl workbooks and number formats and styles.