Instant vs Duration XBRL Concepts and the Balance Sheet Trap

Take 2 facts out of the same 10-K instance document: total assets, and revenue. They look like siblings — a concept, a value, a context reference. But the context behind each one is a fundamentally different kind of thing, and if your parser treats them the same, it will hand you statements that are subtly and expensively wrong.

I want to be blunt about why this matters more than it sounds. The mistakes in this area are the worst kind there are: they never throw, they always return a number, and the number is entirely plausible. Nobody catches them in code review. And they compound — a snapshot-versus-flow mismatch in a ratio, a year-to-date total mistaken for a quarter, a fourth quarter that you have to compute yourself but never knew was missing, a calendar quirk that shows up once every 6 years. Each one produces a confident, wrong answer.

Instant facts and duration facts are not the same object

An XBRL context describes the period a fact covers, and there are exactly 2 flavors. An instant context is a single date — balance-sheet items use it, because a balance is a snapshot as of a moment. A duration context is a start date and an end date — income-statement and cash-flow items use it, because a flow accumulates over an interval.

So “total assets” is anchored to 2025-12-31, while “revenue” is anchored to 2025-01-01 → 2025-12-31. Same filing, same fiscal year, 2 different period objects. A parser that keys everything on a single “period end” string will happily line them up — and it will also happily line up things that must never be lined up.

The balance-sheet trap, and the worse duration trap

The snapshot-versus-flow mismatch. Any ratio that divides an income-statement flow by a balance-sheet stock — return on assets, asset turnover, inventory turns — combines a duration with an instant. Do it carelessly and you divide a full-year flow by a mid-year balance. The number looks plausible and is wrong.

The year-to-date duration trap, which is worse because it hides. A single quarterly 10-Q instance document does not contain just the quarter. It contains multiple durations for the same concept: the 3-month quarter and the 6- or 9-month year-to-date figure, both tagged, both valid, both revenue. Grab “the revenue fact” without checking the exact span of its context and you sometimes take the quarter and sometimes the year-to-date, and your quarterly series has step-changes that look like the business tripled and then collapsed. This is one of the most common defects in home-grown XBRL parsers, and because it produces a plausible number every time, nothing ever raises.

The quarter that is never filed: computing Q4

Now here is the trap that catches you even after you have solved the last one, which is what makes it so annoying. A US domestic filer files 3 10-Qs and one 10-K a year. The 10-Qs give you 3 discrete quarters — but only if you pick the 3-month duration out of each, ignoring the cumulative one. The 10-K gives you the full fiscal year as a 12-month duration. It does not give you a discrete fourth quarter. There is no Q4 10-Q; the fourth quarter is simply never reported as a standalone period. The only way to see it is to subtract: the fourth quarter equals the full year minus the first 9 months.

# The DIY way to recover a discrete Q4 you never subtract for elsewhere:
# fiscal-year revenue (12-month, from the 10-K) minus the nine-month YTD
# revenue (from the Q3 10-Q). Q4 is a derived figure by construction.
fy_revenue      = 62753   # 12-month duration, 10-K
ytd9_revenue    = 45120   # 9-month duration, Q3 10-Q
q4_revenue      = fy_revenue - ytd9_revenue

# Do the same for every income-statement and cash-flow line, every year,
# and get the period math exactly right, or your Q4 column is silently off.

So a clean quarterly series is really 3 durations pulled correctly out of 3 filings plus one figure computed by subtraction — and the subtraction has to happen on the income statement and cash flow but never on the balance sheet, because a stock is not additive across periods. That last rule is another silent failure waiting to happen if you apply the subtraction uniformly.

52/53-week years and other calendar landmines

Suppose you have got all the period math right. You are still not safe, because the calendar underneath it is not tidy. Many retailers and manufacturers run a 52/53-week fiscal year that ends on the last Saturday of a month, so once every 5 or 6 years a fiscal year has an extra week and one of its quarters is 14 weeks long instead of 13. A day-count rule that expects a quarter to be about 90 days has to tolerate that. Fiscal years that do not end in December mean the “same” calendar quarter maps to different fiscal quarters across companies. And a company that changes its fiscal year-end files a short “stub” period that matches none of your buckets. Bucketing durations by their exact day span is the honest way to classify them, but the buckets have real, recurring exceptions that each need handling.

The free route means classifying every context by hand

So let me lay out what doing this correctly yourself actually involves, end to end. For every fact you resolve its context and decide instant or duration; for durations you compute the interval length and keep only the one matching the frequency you want, discarding every year-to-date and prior-period comparative in the document; you derive Q4 by subtraction on flows but never on stocks; you tolerate 53-week years and stub periods in your day-count logic; for instants you keep the period-end and drop the opening balance; and then, when you build a ratio, you align a duration’s end date with the correct instant date. None of it is conceptually hard. All of it is fiddly, per-filing, and unforgiving — and the failures are silent.

Read one normalized period axis instead

That is a lot of bookkeeping, and all of it disappears if the period is resolved before you see it. The Financial Statements API resolves the contexts on ingestion and gives every value a normalized period. Each entry in a line item’s values array carries a date, a normalizedDate and a periodType, so instants and durations arrive on one axis, a quarter is never confused with a year-to-date total, and the derived fourth quarter is already there:

{
  "date": "2025-12-31",
  "normalizedDate": "2025-12-31",
  "periodType": "Quarter",
  "reportedValue": { "raw": 15917000000, "fmt": "15.92B" }
}

You never see a raw context, you never do the Q4 subtraction, and you never write day-count logic. You choose granularity with the frequency parameter, and periodType confirms it:

import requests

API_KEY  = "YOUR_API_KEY"
BASE_URL = "https://data.businessquant.com"

def series(ticker, slug, statement, frequency="Quarter", period="5y"):
    url = (f"{BASE_URL}/statements"
           f"?ticker={ticker}&statement={statement}"
           f"&frequency={frequency}&period={period}&api_key={API_KEY}")
    data = requests.get(url).json()
    for category in data["data"].values():
        for section in category["sections"].values():
            if section["metadata"]["slug"] == slug:
                return {v["normalizedDate"]: v["reportedValue"]["raw"] for v in section["values"]}
    return {}

# A clean quarterly series -- every point is one discrete quarter, including a
# Q4 the server derived for you, never a year-to-date figure, because
# frequency=Quarter fixed the periodType.
rev = series("IBM", "revenue", "IS", frequency="Quarter")
for d in sorted(rev)[-4:]:
    print(d, rev[d])

Aligning a flow with the balance that produced it

A clean quarterly or annual series is the first payoff. The second is ratios. Remember the snapshot-versus-flow mismatch from earlier — dividing a full-year flow by a mid-year balance? Because the balance sheet and income statement share the normalized period axis, that ratio becomes a dictionary lookup on a common date, with no context math:

net_income   = series("IBM", "net-income",   "IS", frequency="Annual")
total_assets = series("IBM", "total-assets", "BS", frequency="Annual")

for d in sorted(net_income):
    if total_assets.get(d):
        roa = net_income[d] / total_assets[d]
        print(d, round(roa * 100, 1), "%")

The duration (net income over the year) and the instant (assets at year-end) meet on the same normalizedDate, because normalization already stamped the flow with the end of its interval. No instant-versus-duration bookkeeping survives into your code. And when you want to be rigorous, the same axis makes the textbook version easy too — return on assets is properly computed against average assets across the period, not the ending stock, which is just a second lookup on the prior period’s date:

# Rigorous ROA: average of beginning and ending assets, not the ending stock.
dates = sorted(net_income)
for i, d in enumerate(dates):
    end = total_assets.get(d)
    beg = total_assets.get(dates[i - 1]) if i else None
    avg = (end + beg) / 2 if (beg and end) else end
    if avg:
        print(d, round(100 * net_income[d] / avg, 1), "%")

Edge cases to keep in mind

The normalized axis handles the hard cases, but a few details are worth knowing so you do not re-introduce the traps it removed.

Pick the frequency, do not derive it. Use frequency=Quarter for discrete quarters and frequency=Annual for fiscal years. You should never be reconstructing a quarter by subtracting one year-to-date figure from another, and you should never be hand-deriving Q4. That is precisely the trap this parameter exists to remove, so please let it.

Stocks are not additive; flows are. The Q4-by-subtraction rule applies to income-statement and cash-flow lines, never to balance-sheet balances. Normalized periods encode this for you, so a balance-sheet value at a quarter-end is the snapshot, not a difference.

TTM is a derived flow. A frequency=TTM series is a rolling 12-month duration; its periodType is TTM, and each point ends on a quarter-end date.

Align on normalizedDate, not the label. When you join statements, key on normalizedDate — the field designed to be identical across statements for the same period, including across 53-week years and non-December fiscal ends.

Start Building

With the edge cases covered, here is how the whole picture fits together. Instant versus duration is a real distinction in XBRL, and it is the source of 4 silent, plausible-looking errors. Mixing a snapshot with a flow. Mistaking a year-to-date total for a quarter. Hunting for a Q4 that nobody ever files. Tripping over a 53-week year that arrives once every 5 or 6 years, right when you have stopped thinking about it.

Normalized periods retire all 4 at once. Choose a frequency, read a normalizedDate, and align your statements by a shared date instead of a resolved context.

• Financial Statements API — every value carries date, normalizedDate and periodType, with Q4 already derived.
• SEC Filings API — the underlying filings and XBRL attachments, to see the raw contexts.

Get an API key, pull a quarterly series, and check every point is a single quarter — including the fourth. That last check is the one I would run first.