--- title: "Get Portfolio Holdings" description: "How to request portfolio holdings data through the Investment Details Feed API." url: "https://developer-beta.morningstar.com/investment-details-feed-api/request-portfolio-holdings" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~R2V0IFBvcnRmb2xpbyBIb2xkaW5ncyB8IEludmVzdG1lbnQgRGV0YWlscyBGZWVkIEFQSQ,description_How+to+request+portfolio+holdings+data+through+the+Investment+Details+Feed+API.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWRldGFpbHMtZmVlZC1hcGkvcmVxdWVzdC1wb3J0Zm9saW8taG9sZGluZ3Mi,s_E6GPccTYHE_4B45e.png" --- - [APIs](https://developer-beta.morningstar.com/apis) - [API Catalog](https://developer-beta.morningstar.com/api-catalog) - [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp) - [Guides](https://developer-beta.morningstar.com/api-guides) - [Trial Access](https://developer-beta.morningstar.com/trial-access) # Investment Details Feed API Get detailed profile data for up to 250 investments in a single request, drawing on Morningstar's fundamental, reference, and historical data.. # Request Portfolio Holdings Data [View Markdown](https://developer-beta.morningstar.com/investment-details-feed-api/request-portfolio-holdings.md)[Download Markdown](https://developer-beta.morningstar.com/investment-details-feed-api/request-portfolio-holdings.md) The Investment Details Feed API supports views derived from these packages. Only the **most recent** data is available for them. - [Full Look Through Portfolio Holdings](https://developer-beta.morningstar.com/investment-details-feed-api/full-look-through-portfolio-holdings) - [Full Portfolio Holdings Month End or Quarter End Most Recent](https://developer-beta.morningstar.com/investment-details-feed-api/full-portfolio-holdings-month-quarter-end) ## [Request Limits](#request-limits) | Input | Limit | | :---------- | :------------------------------- | | investments | Maximum of 1 id per request. | | views | Maximum of 1 viewId per request. | ## [Retrieve Portfolio Dates](#retrieve-portfolio-dates) Use this request to find the portfolio dates available for an investment. ### [1: Specify the Investment](#_1-specify-the-investment) Pass the investment ID as a path parameter. Morningstar Performance ID is the default identifier type. ```text POST /direct-web-services/v1/investments/0P0000004Y/portfolio-holdings-dates ``` To use another identifier, pass it in the path and set `idType` and any lookup filters in the request body. ```text POST /direct-web-services/v1/investments/004239109/portfolio-holdings-dates ``` ```json "idType": "cusip", "exchangeCountry": "USA", "domicile": "USA", "baseCurrency": "USD" ``` ### [2: Specify the Holdings View](#_2-specify-the-holdings-view) In the request body, set `holdingsView` to `10`, `25` or `full`. ```json "holdingsView": "10" ``` ### [Step 3: Specify the Portfolio Dates Type](#step-3-specify-the-portfolio-dates-type) The `type` property is required. Accepted values are `mostRecent`, `timeSeries` and `staticDates`. The last two require additional inputs. **mostRecent.** Returns the most recent date with data for the investment. ```json "type": "mostRecent" ``` **timeSeries.** Returns the dates with data in a time range. `startDate` and `endDate` (`YYYY-MM-DD`) are required. `frequency` is optional: `d` (daily) or `m` (monthly). ```json "type": "timeSeries", "frequency": "d", "startDate": "2026-01-01", "endDate": "2026-06-01" ``` **staticDates.** Returns the dates with data from a list you provide. The `dates` array takes a maximum of 10 dates (`YYYY-MM-DD`). ```json "type": "staticDates", "dates": [ "2025-06-01", "2025-12-01", "2026-06-01" ] ``` ### [4: Send the Request](#_4-send-the-request) The following request combines steps 1 to 3. ```bash curl --request POST \ --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments/0P0000004Y/portfolio-holdings-dates" \ --header "Authorization: Bearer {token}" \ --header "Content-Type: application/json" \ --data '{ "holdingsView": "full", "type": "timeSeries", "startDate": "2025-01-01", "endDate": "2026-06-01" }' ``` ### [5: Choose a Portfolio Date](#_5-choose-a-portfolio-date) The response lists the dates with data for the investment. Choose one to use as `portfolioDate` in your holdings request. ```json { "portfolioDates": [ { "portfolioDate": "2025-08-01", "holdingsView": "Full" }, { "portfolioDate": "2026-03-01", "holdingsView": "Full" } ], "identifiers": { "performanceId": "0P0000004Y" }, "metadata": { "requestId": "41ec7d45-4d13-46fc-acf8-292500708eb1", "time": "2026-10-22T13:24:26.1910242Z" } } ``` ## [Request Portfolio Holdings](#request-portfolio-holdings) For the full list of inputs, see [API Inputs](https://developer-beta.morningstar.com/investment-details-feed-api/api-inputs). ### [1: Specify the Investment](#_1-specify-the-investment-1) Use the `investments` array with a single entry. Morningstar Performance ID is the default identifier type. ```json "investments": [ { "id": "0P0000004Y" } ] ``` To use another identifier, set `idType` on the entry. Accepted types are `performanceId` (default), `isin`, `fundCode`, `securityId`, `cusip`, `msid`, `tradingSymbol` and `industryCode`. ```json "investments": [ { "id": "US0042391096", "idType": "isin", "exchangeCountry": "USA", "domicile": "USA", "baseCurrency": "USD" } ] ``` ### [2: Specify a View](#_2-specify-a-view) Use one of the following view IDs: - `full-look-through-portfolio-holdings` - `full-portfolio-holdings-month-end-or-quarter-end-most-recent` ```json "views": [ { "viewId": "full-look-through-portfolio-holdings" } ] ``` **Optional parameters.** ```json "views": [ { "viewId": "full-look-through-portfolio-holdings", "parameters": { "holdingsView": "Full" } } ] ``` ### [3: Set a Portfolio Date (Optional)](#_3-set-a-portfolio-date-optional) If you omit it, the most recent data is returned. ```json "portfolioDate": "2026-03-01" ``` ## [Send the Request](#send-the-request) ### [Example: Default Inputs](#example-default-inputs) Falls back on the defaults for `holdingsView` (`Top25`) and `portfolioDate` (the most recent date with data). ```bash curl --request POST \ --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments" \ --header "Authorization: Bearer {token}" \ --header "Content-Type: application/json" \ --header "Prefer: respond-async" \ --data '{ "investments": [ { "id": "0P00018P7K", "idType": "performanceId" } ], "views": [ { "viewId": "full-look-through-portfolio-holdings" } ] }' ``` ### [Example: Explicit Inputs](#example-explicit-inputs) Sets `holdingsView` and `portfolioDate`. Same URL and headers. Only the body is shown. ```json { "investments": [ { "id": "0P00018P7K", "idType": "performanceId" } ], "views": [ { "viewId": "full-look-through-portfolio-holdings", "parameters": { "holdingsView": "Full" } } ], "portfolioDate": "2025-06-30" } ``` ## [Read the 202 Response](#read-the-202-response) A valid request returns `202 Accepted` with the job details, not data. ```json { "jobId": "16bf1a7a-c883-4424-8810-2f4e9d244d40", "_links": { "href": "https://www.us-api.morningstar.com/dynamic-services-apis/jobs/16bf1a7a-c883-4424-8810-2f4e9d244d40", "rel": "status", "method": "GET" }, "metadata": { "requestId": "c63e7f6c-b52d-42c3-9d1b-4a4b4ac05f3c", "time": "2025-10-02T10:54:36.9161062Z" } } ``` | Property | Description | | :------------------------ | :------------------------------------------------------------ | | jobId | Identifier of the job. | | _links.href | URL to call to check the job status. | | _links.rel, _links.method | Always status and GET. | | metadata.requestId | Identifier of the request. Include it if you contact support. | | metadata.time | Time of the response. | To check the job and retrieve results, see [Retrieve Investment Details](https://developer-beta.morningstar.com/investment-details-feed-api/retrieve-results). ## [Retrieve Results](#retrieve-results) To check the job and retrieve results, see [Retrieve Investment Details](https://developer-beta.morningstar.com/investment-details-feed-api/retrieve-results). ## [Results](#results) The response has two top-level properties. | Property | Description | | :---------- | :-------------------------------------------------------------------------- | | investments | An array with one object for each investment that returned data. | | metadata | Information about the response: the request ID, the time, and any messages. | ### [Investments](#investments) Each object in `investments` is one investment. It has the following characteristics. - **Holdings.** The `holdings` object holds the investment's performance ID. Use it to match the data to the investments in your request. - **Identifiers.** The `identifiers` object holds the investment's performance ID. Use it to match the data to the investments in your request. - **Data groups.** The remaining properties are data groups, named for the data they hold. The groups depend on the views you requested. - **Objects and arrays.** A group is an object when there is one record, and an array when there can be several, such as time series values or several reporting periods. In the example above, `profitability` is an array. - **Coded values.** Some values are returned as an object with a `value` and a `code`, for example `{ "value": "US Dollar", "code": "USD" }`. - **Language and country.** Data that depends on language or country uses the `languageId` and `countryId` from your request. ### [Metadata](#metadata) See [Work with Results](https://developer-beta.morningstar.com/investment-details-feed-api/work-with-investment-details-results) for information about metadata and metadata messages. ### [Example Results](#example-results) ```json { "investments": [ { "holdings": [ { "detailHoldingTypeCode": "B", "portfolioWeightingPercentage": 4.21564, "positionMarketValue": 608371.9999999993, "maturityDate": "2049-12-31", "detailHoldingType": { "value": "BOND - CORPORATE BOND", "code": "B" }, "holdingStorageId": "1", "securityName": "Bnp Paribas Ser Regs (Reg) (Reg S) Var Perp" }, { "detailHoldingTypeCode": "BT", "portfolioWeightingPercentage": 3.49419, "positionMarketValue": 504256.9999999994, "maturityDate": "2030-11-13", "detailHoldingType": { "value": "BOND - GOV'T/TREASURY", "code": "BT" }, "holdingStorageId": "2", "securityName": "China Cinda 2020 1 Mngmn Ser Emtn" } ], "identifiers": { "performanceId": "0P00018P7K" }, "metadata": { "time": "2026-10-23T15:19:02.968016Z", "portfolioDate": "2026-06-30", "portfolioCurrency": "USD" } } ], "metadata": { "requestId": "aeae4dca-8113-43ce-8155-b2e88e5b295a", "time": "2026-10-23T15:19:02.8820276Z" } ```