---
title: "Holders-of-CUSIP Δ over the last N retained quarters"
method: GET
path: "/api/v1/sec/13f/holders-of/{cusip}/changes"
tags: ["Hedge Fund Intelligence"]
---

# Holders-of-CUSIP Δ over the last N retained quarters

`GET /api/v1/sec/13f/holders-of/{cusip}/changes`

Holder-level delta for one CUSIP across the N most-recent retained quarters (default 2, max 4 by memory bound). Computes added / removed / changed holders comparing earliest vs latest stem in the window. Intermediate stems contribute to `consensus_trend` (per-stem holder_count + total value + total shares) for sparkline rendering. `quarters_used` echoes the effective N. Out-of-range (1 or 5+) is REJECTED with 400 - no silent clamping. Internally uses streaming diff to bound memory ~one shard regardless of N.

## Path parameters

- `cusip` string, required — 9-character canonical CUSIP.

## Query parameters

- `quarters` integer — Number of retained quarters to compare (range 2-4 inclusive). Out-of-range = 400; no silent clamping.

## Response `200`

Multi-quarter delta-holders + consensus trend for one CUSIP.

- EnvelopeSec13fCusipChanges
  - `data` Sec13fCusipChanges, required — Delta-holders for one CUSIP over N quarters (2-4 per memory bound).
    - `comparison` Sec13fComparison — The interval a comparison actually covers. The baseline quarter is chosen from what retention holds, not from the calendar, so when a quarter is missing the two compared quarters are not adjacent and the delta spans more than one. Without this block the response would describe six months in the words of three.
      - `from_period_end` string, nullable — Reported quarter-end of the baseline.
      - `to_period_end` string, nullable — Reported quarter-end of the target.
      - `quarters_apart` integer, nullable — How many quarters the comparison covers; 1 is quarter-over-quarter. Null when the interval cannot be determined.
      - `calendar_adjacent` boolean, nullable — Whether the two quarters are consecutive. Absent when the interval could not be determined - false would read as a known answer.
      - `skipped_quarters` string[], nullable — Reported quarter-ends lying between the two that this comparison does not cover.
      - `note` string, nullable — Present only when quarters were skipped.
    - `cusip` string, required
    - `issuer` string, required
    - `quarters_used` integer, required — Effective number of quarters in the comparison (echoes request).
    - `quarters` Sec13fQuarter[], required — The N stems queried, oldest -> newest.
      - `stem` string, required — Filing-window stem.
      - `period_end` string, required — ISO date of quarter end.
      - `fetched_at` string, required — When this stem was ingested.
      - `filers_count` integer, required — Distinct filers in this quarter.
      - `holdings_count` integer, required — Total INFOTABLE rows after amendment dedup.
      - `notices_count` integer, nullable — Count of 13F-NT notices indexed for this quarter (B1).
    - `holders_added` Sec13fHolder[], required — In latest only.
      - `issuer` string, required
      - `title` string, required
      - `cusip` string, required
      - `figi` string, nullable
      - `value_usd_thousands` integer, nullable
      - `shares` integer, nullable
      - `shares_type` string, required
      - `put_call` string, nullable
      - `investment_discretion` string, required
      - `voting_sole` integer, required
      - `voting_shared` integer, required
      - `voting_none` integer, required
      - `accession` string, required
      - `period_of_report` string, required
      - `cik` string, required
      - `manager_name` string, required
    - `holders_removed` Sec13fHolder[], required — In earliest only.
      - `issuer` string, required
      - `title` string, required
      - `cusip` string, required
      - `figi` string, nullable
      - `value_usd_thousands` integer, nullable
      - `shares` integer, nullable
      - `shares_type` string, required
      - `put_call` string, nullable
      - `investment_discretion` string, required
      - `voting_sole` integer, required
      - `voting_shared` integer, required
      - `voting_none` integer, required
      - `accession` string, required
      - `period_of_report` string, required
      - `cik` string, required
      - `manager_name` string, required
    - `holders_changed` Sec13fHolderDelta[], required — In earliest+latest, value or shares differ.
      - `cik` string, required
      - `manager_name` string, required
      - `value_usd_thousands_from` integer, nullable
      - `value_usd_thousands_to` integer, nullable
      - `value_usd_thousands_delta` integer, nullable
      - `shares_from` integer, nullable
      - `shares_to` integer, nullable
      - `shares_delta` integer, nullable
    - `consensus_trend` Sec13fConsensusTrendPoint[], required — Per-stem aggregate count / value / shares across all N quarters, oldest -> newest.
      - `stem` string, required
      - `holder_count` integer, nullable — Holder count for this stem. Null when `available=false` because the underlying CUSIP shard failed to load (blob 404 / parse / network). Distinguishes 'shard unavailable' from 'legitimate zero holders'.
      - `total_value_usd_thousands` integer, nullable — Sum of reported value across holders. Null when `available=false`.
      - `total_shares` integer, nullable — Sum of share count across holders. Null when `available=false`.
      - `available` boolean — True when the underlying shard loaded successfully and the count / value / shares are real aggregates. False when shard load failed - count / value / shares are null in that case (prevents the prior false 'drop to zero' trend artifact).
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/652554d2aae1/schema)