--- title: "List fund letters" method: GET path: "/v1/fund-letters" tags: ["Fund Letters"] --- # List fund letters `GET /v1/fund-letters` ## Request - Base URL: `https://api.fiscal.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.fiscal.ai/v1/fund-letters` - Auth: API key in query parameter `apiKey` Lists the published fund letters for one calendar year (optionally one quarter) — quarterly, annual and interim letters from hedge funds, mutual funds, investment partnerships and other professional investors, with extracted per-company theses available via the letter detail endpoint. Rows are sorted by reporting period, newest first. Narrow further with quarter, or with investorId/fundId from the investors endpoints (an investor's complete letter feed across all years is on /v1/fund-letters/investors/{investorId}). Every row carries the companies the letter discusses (companyKeys), so the list is also a cheap way to scan a period's coverage. A period with no published letters returns an empty page, not an error. The corpus is curated: only complete, quality-checked letters from 2020 onward are published, and each letter appears once (the same letter distributed through multiple channels is deduplicated). Identifiers are permanent; counts can drift slightly between daily publishes as new letters arrive and the company universe evolves. Letters are published once a day. A letter can be revised after publishing under the same letterId (corrected content, or a better copy of its PDF): compare each row's updatedAt with the one you hold and re-fetch only the letters that moved, and the PDF only when pdfSha256 changed. New letters can appear in past years, so a full sync lists every year from 2020. Free-trial keys receive the letters of the investors listed by /v1/fund-letters/investors. ## Query parameters - `apiKey` string: API Key (alternatively send via X-Api-Key header) - `year` integer, required: Calendar year of the reporting period (2020 or later). Required. - `quarter` integer: Optional. Calendar quarter (1-4) within the year. Omit for the whole year. - `investorId` string: Optional. Only letters from this investor (fscl_investor_… identifier). - `fundId` string: Optional. Only letters from this fund (fscl_fund_… identifier). - `pageNumber` integer: Optional. Page number (1-indexed). Defaults to 1. - `pageSize` integer: Optional. Rows per page. Defaults to 250, max 1000. ## Response `200` Paginated fund letters, newest reporting period first. - object - `pagination` object, required - `page` number, required: Current page number (1-indexed). - `pageSize` number, required: Number of items per page. - `totalCount` number, required: Total number of rows matching the request. - `totalPages` number, required: Total number of pages. - `hasNextPage` boolean, required: Whether there is a next page. - `hasPreviousPage` boolean, required: Whether there is a previous page. - `data` object[], required - `letterId` string, required: Permanent identifier of this fund letter. Stable across publishes — use it to fetch the letter detail and PDF. - `investorId` string, required: Permanent identifier of the investment firm that published the letter. - `fundId` string, required: Permanent identifier of the specific fund/vehicle the letter reports on. - `investorName` string, required: Canonical investment-firm name. - `fundName` string, required: Canonical fund/vehicle name. - `fundType` string, required: Normalized fund vehicle classification (e.g. hedge_fund, mutual_fund, investment_partnership, closed_end_fund, etf, holding_company). - `title` string, required: Letter title as published. Nullable. - `reportPeriod` string, required: Canonical reporting period as a YYYYQn key — the same format as firstPeriod/latestPeriod everywhere in this API. - `reportPeriodYear` number, required: Calendar year of the reporting period. - `reportPeriodQuarter` number, required: Calendar quarter (1-4) of the reporting period. Annual letters are assigned the quarter their period ends in. - `reportPeriodType` string, required: Reporting cadence: annual, semiannual, quarterly, monthly, other, or unknown. - `periodLabel` string, required: The reporting period exactly as the letter states it (free text). Nullable. - `publicationDate` string, required: Publication date (YYYY-MM-DD) when the letter states one. Nullable. - `letterType` string, required: Normalized document type (e.g. quarterly_letter, annual_letter, monthly_commentary, shareholder_letter, fund_commentary). - `thesisCount` number, required: Number of company theses extracted from this letter (0 for pure macro letters). - `keyTopics` string[], required: Normalized topics the letter discusses beyond individual companies. - `companyKeys` string[], required: Company keys (EXCHANGE_TICKER) of every company with a thesis in this letter. - `companyTickers` string[], required: Primary-listing tickers matching companyKeys, in the same order. - `firstPublishedAt` string, required: When this letter first became available through the API (ISO 8601, UTC). - `updatedAt` string, required: When this letter's content or PDF last changed (ISO 8601, UTC); equal to firstPublishedAt until the letter is revised. Refreshed company data on each thesis (names, classification, market cap) is not a revision and does not move it. - `pdfSha256` string, required: SHA-256 of the PDF served by /v1/fund-letters/{letterId}/pdf; it changes when the document is replaced. Nullable. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found ## Changes - **2026-10-20** `eb2f5f533070`: 3 info - added the required property `data/items/firstPublishedAt` to the response with the `200` status - added the required property `data/items/pdfSha256` to the response with the `200` status - added the required property `data/items/updatedAt` to the response with the `200` status [Operation history](https://skmtc.dev/fiscal/apis/fiscal-api/changes/v1/fund-letters/get.md) --- [API](https://skmtc.dev/fiscal/apis/fiscal-api.md) - [All operations](https://skmtc.dev/fiscal/apis/fiscal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fiscal/apis/fiscal-api/revisions/85026fdfc8b8?raw)