SEC Trading Suspension API for Event-Driven Research

Use the SEC Trading Suspension API to build a dated cohort from Section 12(k) orders, while treating each suspension as a regulatory event rather than proof of fraud or a short recommendation.

Alphanume's endpoint is GET /v1/market-structure/sec-suspensions. It covers SEC trading-suspension orders from 1995 forward and stores one row for each issuer named in an order. A release that covers several issuers therefore becomes several records, linked by release_number and distinguished by issuer_index.

For event-driven research, the useful part is the clock. date is the SEC release date, while suspended_at is the suspension start date and suspension_start_time_et supplies the stated Eastern Time start. Those can differ. The legal window uses suspension_end_at with suspension_end_time_et, and resumption_at marks the first NYSE session strictly after termination when trading may resume. Permission to resume is not proof that quoting or liquidity actually returned.

Start with the event contract

The normalized cited_reason values include delinquent filings, market manipulation, accuracy or adequacy of information, and other. cited_reason_detail retains more specific text. These fields categorize what the order says. They are not findings of guilt, realized returns, delisting decisions, or instructions to short a security.

Query a range and keep every page

The API supports exact date or date-range filters, plus ticker, CIK, release number, reason, issuer name, resumption state, single-issuer orders, active_on, and updated_since. Do not combine exact date with range parameters. Results use deterministic keyset pagination ordered by descending date, then release number and issuer index.

import os
import requests

url = "https://api.alphanume.com/v1/market-structure/sec-suspensions"
params = {"date_gte": "2024-01-01", "date_lte": "2024-12-31"}
headers = {"X-API-Key": os.environ["ALPHANUME_API_KEY"]}
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.update({
        "cursor_date": cursor["date"],
        "cursor_release_number": cursor["release_number"],
        "cursor_issuer_index": cursor["issuer_index"],
    })

assert len({row["record_id"] for row in rows}) == len(rows)

The current corpus can fit inside one large page, but code should still honor has_more. That protects the workflow as coverage grows and prevents a smaller page setting from silently changing the cohort. Save each raw page before converting the rows to pandas.

Export the correct event date

A pandas event table should retain the release date plus the separate effective date and time fields. If the study measures the market after trading was halted, combine suspended_at with suspension_start_time_et under the documented New York timezone. If it measures the information event of the SEC publication, use date and document that no release time is served. One generic date column loses that distinction.

import pandas as pd

events = pd.DataFrame(rows)
events["release_date"] = pd.to_datetime(events["date"])
events["suspension_start_timestamp_et"] = pd.to_datetime(
    events["suspended_at"] + " " + events["suspension_start_time_et"]
).dt.tz_localize("America/New_York")

cohort = events[[
    "record_id", "release_number", "issuer_index", "issuer_count", "issuer_name",
    "ticker", "cik", "release_date", "suspended_at", "suspension_start_time_et",
    "suspension_start_timestamp_et", "suspension_end_at",
    "suspension_end_time_et", "resumption_at", "cited_reason", "order_url",
]].copy()

cohort.to_parquet("sec_suspension_events.parquet", index=False)

Keep rows with null tickers. Dropping them changes the population toward better-identified issuers, which can bias a historical study. Entity resolution can use issuer name, CIK where present, order text, and a dated security master, with unresolved cases reported rather than guessed.

Separate the order from the outcome

• Maximum duration. Section 12(k) suspensions last no more than 10 business days, so the order itself is not a permanent delisting.
• Reason versus proof. A cited concern records the SEC's stated reason and does not establish fraud by the issuer or any person.
• Legal resumption versus market activity. resumption_at says when trading may resume, not whether a venue quoted the security.
• Sparse recent windows. A short access window can contain zero suspensions because the event is infrequent.
• Identifier gaps. Ticker, CIK, and venue can be null, especially in older or thinly traded cases.

Later returns, bankruptcy, enforcement, and delisting are separate outcomes that need separately timed sources. Do not backfill them into the suspension record as though the order knew the future.

Build one auditable cohort

Run the one-year query, save every raw page, and export the two-clock event table. Check a sample of cited_reason values against order_url, then report unresolved identifiers and null timestamps. Only after that audit should you join prices with a written rule for halted sessions and missing quotes.

The SEC Trading Suspensions field reference lists all filters and response fields. Explore the dataset context on the SEC Trading Suspensions page, and use the regulatory-events topic hub for adjacent event-timing workflows.