Shelf-Registration Data API for Quant Research

Query S-3 and F-3 shelf registrations as a dated financing-capacity ledger, then monitor effectiveness and takedown evidence without equating authorization with issuance.

A shelf-registration data API should tell a researcher when an issuer registered financing capacity, which securities the filing covered, whether it was a primary or resale shelf, and how the filing's lifecycle changed. Alphanume's Shelf Registrations dataset stores base filings, amendments, and automatic WKSI shelves as separate point-in-time rows.

The central rule is that authorization is not issuance. capacity_amount is the amount a shelf registers, not the amount sold. A linked 424B5 takedown is evidence of later activity, but takedown_count is not a complete usage ledger. Keep registration, effectiveness, takedown, and actual issuance as distinct events.

Read the capacity ledger correctly

A capacity-to-market-cap ratio can rank filings for review, but only when both values are non-null and the shelf is economically comparable. Automatic shelves often have indeterminate capacity. Resale shelves represent selling holders rather than new issuer proceeds. A single ratio that converts either case to zero creates a misleading cross-sectional ranking.

Query one fixed quarter

The endpoint is GET /v1/capital/shelf-registrations. It accepts exact dates, date ranges, ticker, CIK, form, shelf type, and updated_since. This request retrieves filings from one completed quarter and paginates with the documented two-part cursor.

import os
import requests

url = "https://api.alphanume.com/v1/capital/shelf-registrations"
headers = {"X-API-Key": os.environ["ALPHANUME_API_KEY"]}
params = {"date_gte": "2026-04-01", "date_lte": "2026-06-30"}
rows = []

while True:
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()
    rows.extend(payload["data"])
    if not payload.get("has_more"):
        break
    cursor = payload["next_cursor"]
    params["cursor_date"] = cursor["date"]
    params["cursor_accession"] = cursor["accession_number"]

Both cursor values are required together. Results are ordered by filing date descending and accession number ascending. The Shelf Registrations API reference documents the field set, null rules, and lifecycle behavior.

Create a reproducible monitoring table

Save the base filing facts separately from mutable lifecycle fields. last_updated moves forward when EFFECT or takedown refreshes change a row. An incremental monitor should query updated_since, archive the new version, and calculate what changed rather than overwriting the original research snapshot.

monitor_columns = [
    "record_id",
    "date",
    "filing_timestamp",
    "ticker",
    "form",
    "shelf_type",
    "capacity_amount",
    "is_resale",
    "became_effective",
    "effective_at",
    "takedown_count",
    "first_takedown_at",
    "market_cap_at_filing",
    "filing_url",
    "last_updated",
]

monitor = [{key: row.get(key) for key in monitor_columns} for row in rows]

For a fresh-primary-capacity screen, a researcher can review shelf_type=new and is_resale=0, then calculate capacity relative to market cap only for non-null rows. This is a queue for filing review. It is not evidence that the issuer sold the securities or that price impact followed.

Keep the unfiltered denominator beside that screen. Otherwise, dropping resale, automatic, amendment, refused, and null-capacity rows can make a sparse eligible sample look like the complete shelf universe. Report counts at each filter and retain every excluded accession number with one machine-readable reason.

Interpret effectiveness and takedowns cautiously

An EFFECT notice establishes that a non-automatic shelf became effective. Automatic shelves can be effective on filing. expiry_estimate is generally effectiveness plus three years, but actual expiry can differ under transition rules or early replacement. Treat it as an estimate, not a guaranteed termination date.

Takedown counts are refreshed for shelves filed in the trailing 400 days. Older shelves can have counts frozen at their last refresh. A zero count can therefore mean no linked takedown was observed under the serving logic, not proof that no security was issued through another mechanism.

Handle refusals, nulls, and access

• Rows with refused equal to 1 represent real filings the extraction model declined to label; extracted fields can be null.
• Automatic and indeterminate shelves have null capacity by design.
• Market cap and outstanding shares can be null when point-in-time context is unavailable.
• Amendments should not be merged into a base row without an explicit file-number lifecycle rule.
• Free access provides a rolling 30-day delayed window, with the latest observation reserved for Pro.

A short window can validate the monitor but cannot describe several financing regimes. A capacity study also needs an external outcome definition, price adjustments, delisting handling, and transaction costs before it can make a trading claim.

Run one capacity audit

Pull one completed quarter, save every raw page, and export separate tables for new primary shelves, resale shelves, automatic shelves, amendments, and refused rows. Verify five filing URLs and every top capacity ratio. Then run updated_since on a later date and confirm that lifecycle changes append to the audit history. The shelf takedown workflow is the next implementation reference after the base ledger reproduces.