---
title: "S&P 500 constituents (membership metadata)"
method: GET
path: "/api/v1/equities/sp500/constituents"
tags: ["Equities Indices"]
---

# S&P 500 constituents (membership metadata)

`GET /api/v1/equities/sp500/constituents`

Returns the full S&P 500 constituent list (503 entries) with GICS sector + sub-industry classifications + date-added + SEC EDGAR CIK identifiers. Sourced from public Wikipedia (CC-BY-SA-4.0) membership announcements via daily auto-refresh blob; hardcoded 503-entry snapshot serves as defence-in-depth fallback when the blob is unavailable. Filter by ``?sector=<GICS sector>`` or ``?sub_industry=<GICS sub-industry>`` to narrow the list. Use case: UC-2 Earnings Whiplash Map filters earnings calendar by SPX members; UC-1 Institutional Footprint cross-references CIK to /sec/13f endpoints. The ``data_source`` field exposes whether the response was served from the Wikipedia blob (``blob_wikipedia``) or the hardcoded fallback (``hardcoded_fallback``).

## Query parameters

- `sector` string, nullable — Optional GICS Level 1 sector filter. Case-sensitive. Returns 400 with the canonical 11-sector list when the value is not in the GICS taxonomy.
- `sub_industry` string, nullable — Optional GICS Level 4 sub-industry filter. Case-sensitive. Returns 400 with the observed catalog when the value is not present in the current data source.

## Response `200`

Filtered S&P 500 constituents with provenance.

- EnvelopeSpxConstituentsPayload
  - `data` SpxConstituentsPayload, required — S&P 500 constituents list with curation provenance. v1.1 scope (GAP-3.3 2026-05-23): full 503-entry index list, served from a daily Wikipedia auto-refresh blob with a hardcoded 503-entry snapshot as defence-in-depth fallback. The endpoint never returns fewer than 503 constituents.
    - `constituents` SpxConstituent[], required — Filtered constituent list (alphabetical by ticker for stable ordering).
      - `ticker` string, required — Stock symbol on NYSE / Nasdaq.
      - `name` string, required — Company name as listed in S&P membership announcements.
      - `gics_sector` string, required — GICS Level 1 sector (1 of 11 canonical sectors).
      - `gics_sub_industry` string, required — GICS Level 4 sub-industry classification.
      - `date_added` string, nullable — ISO date the company was added to the S&P 500 index. ``null`` when the upstream Wikipedia row has a non-ISO value (legacy entries with just year or 'unknown'). Codex R1 P3 #2.
      - `cik` string, required — 10-digit zero-padded SEC EDGAR CIK identifier (cross-link to /sec/13f and other EDGAR endpoints).
    - `count` integer, required — Number of constituents returned after filtering.
    - `as_of_date` string, required — ISO date of the snapshot underpinning this response (blob fetch date or hardcoded curation timestamp).
    - `data_source` string, required — Provenance of the data in this response. ``blob_wikipedia`` means the daily Wikipedia auto-refresh blob was served. ``hardcoded_fallback`` means the blob was missing or unreadable and the static 503-entry snapshot was served instead.
    - `parse_status` string, nullable — Parse status echoed from the ingest blob (``ok`` or ``partial_parse``). ``null`` when the response was served from the hardcoded fallback path (no blob involved).
    - `methodology` string, required — Plain-English description of curation source and refresh cadence.
    - `license_attribution` string, required — Provenance and license string. S&P 500 list curated from public Wikipedia source (CC-BY-SA-4.0); Wikipedia content reflects S&P Dow Jones Indices LLC public membership announcements.
  - `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.
- `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/4e2740743eb4/schema)