Holdings Data Asynchronous#

Creates an asynchronous task that fetches base level holdings details for the specified investments. Note that if none of the date parameters are provided, the function uses latest portfolio date by default.

Parameters:

investments (Union, required) –
Defines the investments to fetch. Input can be:
- Investment IDs (list, optional): Investment identifiers, in the format of SecId;Universe or just SecId. E.g., [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”]. Use the investments function to discover identifiers.
- Investment List ID (str, optional): Saved investment list in Morningstar Direct. Currently, this function does not support lists that combine investments and user-created portfolios. Use the get_investment_lists function to discover saved lists.
- Search Criteria ID (str, optional): Saved search criteria in Morningstar Direct. Use the get_search_criteria function to discover saved search criteria.
- Search Criteria Condition (dict, optional): Search criteria definition. See details in the Reference section below or use the get_search_criteria_conditions function to discover the definition of a saved search criteria.
- InvestmentIdentifiers (list, optional): A list of InvestmentIdentifier objects, allowing users to specify investments using standard identifiers such as ISIN, CUSIP, and/or ticker symbol instead of Morningstar SecIds.
  - Multiple Matches: If multiple valid matches exist for a single InvestmentIdentifier, results will be prioritized according to the security matching logic. The highest ranked security will be used.
  - Request Limit: Supports up to 500 InvestmentIdentifier objects per request.
date (str, list[str], optional) – The portfolio date for which to retrieve data. The format is YYYY-MM-DD. For example, “2020-01-01”. If a date is provided, then the start_date and end_date parameters are ignored. Can also be a list of dates. The list can contain a maximum of 20 dates. An exception is thrown if start_date or end_date is provided along with date.
start_date (str, optional) – The start date for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with start_date.
end_date (str, optional) – The end date for retrieving data. If no value is provided for end_date, current date will be used. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with end_date.
data_points (Union, optional) –
Defines the data points to fetch. If no data points are provided, a default list of data points with predefined aliases are returned, below are the list of default data points and associated aliases.
- Data Point IDs (List[Dict], optional): A list of dictionaries, each defining a data point and its (optional) associated settings. If an alias is provided in the data point setting, it will be used as the column name in the returned DataFrame. Otherwise, the data point ID will be used as the column name.
- Data Point Settings (DataFrame, optional): A DataFrame of data point identifiers and their associated settings. Use the get_data_set_details function to discover data point settings from a saved data set.
frequency (md.direct.data_type.Frequency, optional) –
Frequency at which data point values are retrieved. The default is Frequency.monthly.
- daily: Portfolio holdings data reported daily.
- monthly: Portfolio holdings data reported on or close to the month-end calendar dates.
holdings_view (Union, optional) –
Specifies the level of detail returned for portfolio holdings. This can be an integer or md.direct.data_type.HoldingsView. The default is HoldingsView.FULL.
- Integer Value N: Returns only top N holdings for each portfolio.
- FULL: Returns all available holdings for the portfolio on requested dates.
- BEST_AVAILABLE: Returns the most complete holdings data available for each requested date.
suppression_client_id (str, optional) – If you have a privileged access to suppressed portfolios and would like to apply it, provide your Client ID.
enrichment_type (md.direct.data_type.EnrichmentType, optional) –
Specifies the enrichment type of the data returned. The default is EnrichmentType.POINT_IN_TIME.
- LATEST_AVAILABLE: Uses the most current data at feed generation time.
- POINT_IN_TIME: Matches the data to each portfolio’s effective date.
- LATEST_MONTH_END: Uses the latest available month-end data at request time.
dry_run (bool, optional) – When True, the query will not be executed. Instead, a DryRunResults object will be returned with details about the query’s impact on daily cell limit usage.
preview (bool, optional) – Defaults to False. Setting to True allows access to data points outside of your current subscription, but limits the output to 25 rows.

Returns:

There are two return types:

String: Returns created task id.

Once the task is created, use the get_task_status function to check the status of the task. Then, use the get_holdings_task_result function to retrieve the DataFrame once the task is completed. These are the columns returned:

masterPortfolioId
secIds
portfolioCurrency
portfolioDate
holdingsView
holdingStorageId
secId
name
defaultHoldingTypeCode
isin
cusip
weight
shares
marketValue
sharesChanged
ticker
currency
detailHoldingType
Other columns based on requested data points (column name will be the alias if provided, otherwise the data point ID)

DryRunResults: Is returned if dry_run=True is passed

estimated_cells_used: Number of cells used by this query
daily_cells_remaining_before: How many cells are remaining in your daily cell limit before running this query
daily_cells_remaining_after: How many cells would be remaining in your daily cell limit after running this query
daily_cell_limit: Your total daily cell limit

Raises:

ValueErrorException – Raised when input parameters are invalid.

Examples:

Retrieve holdings for investment “FOUSA00KZH” on “2020-12-31”.

import morningstar_data as md

task_id = md.direct.get_holdings_task(investments=["FOUSA00KZH"], date="2020-12-31")
task_id

Output:: ‘10000000-0000-0000-0000-000000000000’

Example asynchronous workflow#

Retrieve holdings for investment “FOUSA00KZH” on “2020-12-31”. Please refer to get_task_status and get_holdings_task_result documentation on this page.

import morningstar_data as md

task_id = md.direct.get_holdings_task(investments=["FOUSA00KZH"], date="2020-12-31")

status = md.mdapi.get_task_status(task_id)

df = md.direct.get_holdings_task_result(s3_url=status.result.pages[0].url)
df

Output:

masterPortfolioId	secIds	…	currency	detailHoldingType
6079	FOUSA00KZH	…	US Dollar	EQUITY
6079	FOUSA00KZH	…	US Dollar	EQUITY
…

Creates an asynchronous task that fetches holdings details and expands all holdings into their nested underlying securities. Note that if none of the date parameters are provided, the function uses latest portfolio date by default.

Parameters:

investments (Union, required) –
Defines the investments to fetch. Input can be:
- Investment IDs (list, optional): Investment identifiers, in the format of SecId;Universe or just SecId. E.g., [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”]. Use the investments function to discover identifiers.
- Investment List ID (str, optional): Saved investment list in Morningstar Direct. Currently, this function does not support lists that combine investments and user-created portfolios. Use the get_investment_lists function to discover saved lists.
- Search Criteria ID (str, optional): Saved search criteria in Morningstar Direct. Use the get_search_criteria function to discover saved search criteria.
- Search Criteria Condition (dict, optional): Search criteria definition. See details in the Reference section below or use the get_search_criteria_conditions function to discover the definition of a saved search criteria.
- InvestmentIdentifiers (list, optional): A list of InvestmentIdentifier objects, allowing users to specify investments using standard identifiers such as ISIN, CUSIP, and/or ticker symbol instead of Morningstar SecIds.
  - Multiple Matches: If multiple valid matches exist for a single InvestmentIdentifier, results will be prioritized according to the security matching logic. The highest ranked security will be used.
  - Request Limit: Supports up to 500 InvestmentIdentifier objects per request.
date (str, list[str], optional) – The portfolio date for which to retrieve data. The format is YYYY-MM-DD. For example, “2020-01-01”. If a date is provided, then the start_date and end_date parameters are ignored. Can also be a list of dates. The list can contain a maximum of 20 dates. An exception is thrown if start_date or end_date is provided along with date.
start_date (str, optional) – The start date for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with start_date.
end_date (str, optional) – The end date for retrieving data. If no value is provided for end_date, current date will be used. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with end_date.
data_points (Union, optional) –
Defines the data points to fetch. If no data points are provided, a default list of data points with predefined aliases are returned, below are the list of default data points and associated aliases.
- Data Point IDs (List[Dict], optional): A list of dictionaries, each defining a data point and its (optional) associated settings. If an alias is provided in the data point setting, it will be used as the column name in the returned DataFrame. Otherwise, the data point ID will be used as the column name.
- Data Point Settings (DataFrame, optional): A DataFrame of data point identifiers and their associated settings. Use the get_data_set_details function to discover data point settings from a saved data set.
frequency (md.direct.data_type.Frequency, optional) –
Frequency at which data point values are retrieved. The default is Frequency.monthly.
- daily: Portfolio holdings data reported daily.
- monthly: Portfolio holdings data reported on or close to the month-end calendar dates.
holdings_view (Union, optional) –
Specifies the level of detail returned for portfolio holdings. This can be an integer or md.direct.data_type.HoldingsView. The default is HoldingsView.FULL.
- Integer Value N: Returns only top N holdings for each portfolio.
- FULL: Returns all available holdings for the portfolio on requested dates.
- BEST_AVAILABLE: Returns the most complete holdings data available for each requested date.
suppression_client_id (str, optional) – If you have a privileged access to suppressed portfolios and would like to apply it, provide your Client ID.
enrichment_type (md.direct.data_type.EnrichmentType, optional) –
Specifies the enrichment type of the data returned. The default is EnrichmentType.POINT_IN_TIME.
- LATEST_AVAILABLE: Uses the most current data at feed generation time.
- POINT_IN_TIME: Matches the data to each portfolio’s effective date.
- LATEST_MONTH_END: Uses the latest available month-end data at request time.
dry_run (bool, optional) – When True, the query will not be executed. Instead, a DryRunResults object will be returned with details about the query’s impact on daily cell limit usage.
preview (bool, optional) – Defaults to False. Setting to True allows access to data points outside of your current subscription, but limits the output to 25 rows.

Returns:

There are two return types:

String: Returns created task id.

Once the task is created, use the get_task_status function to check the status of the task. And use the get_holdings_task_result function to retrieve the result data once the task is completed. These are the columns returned in the resultant dataframe:

masterPortfolioId
secIds
portfolioCurrency
portfolioDate
holdingsView
holdingStorageId
secId
name
defaultHoldingTypeCode
weight
Other columns based on requested data points (column name will be the alias if provided, otherwise the data point ID)

DryRunResults: Is returned if dry_run=True is passed

estimated_cells_used: Number of cells by this query
daily_cells_remaining_before: How many cells are remaining in your daily cell limit before running this query
daily_cells_remaining_after: How many cells would be remaining in your daily cell limit after running this query
daily_cell_limit: Your total daily cell limit

Raises:

ValueErrorException – Raised when input parameters are invalid.

Examples:

Retrieve holdings for investment “FOUSA00KZH” on “2020-12-31”.

import morningstar_data as md

task_id = md.direct.get_lookthrough_holdings_task(investments=["FOUSA00KZH"], date="2020-12-31")
task_id

Output:: ‘10000000-0000-0000-0000-000000000000’

Example asynchronous workflow#

Retrieve holdings for investment “FOUSA00KZH” on “2020-12-31”. Please refer to get_task_status and get_holdings_task_result documentation on this page.

import morningstar_data as md

task_id = md.direct.get_lookthrough_holdings_task(investments=["FOUSA00KZH"], date="2020-12-31")

status = md.mdapi.get_task_status(task_id)

df = md.direct.get_holdings_task_result(s3_url=status.result.pages[0].url)
df

Output:

masterPortfolioId	secIds	…	defaultHoldingTypeCode	weight
1356725	F00000WK3T	…	E	11.16649
1356725	F00000WK3T	…	E	10.49672
…

morningstar_data.direct.get_holdings_task_result( s3_url: str, flatten_secids: bool = True, ) → DataFrame#

Given an S3 URL from get_task_status, fetches the holdings data and returns it as a DataFrame.

Parameters:

s3_url (str, required) – S3 URL to fetch the holdings data from.
flatten_secids (bool, optional) – Default is True. If set to False, the ‘secIds’ column will be a list of investment ids.

Examples:

task_id = md.direct.get_lookthrough_holdings_task(investments=[“FOUSA00KZH”], date=”2020-12-31”)

status = md.mdapi.get_task_status(task_id)

df = md.direct.get_holdings_task_result(s3_url=status.result.pages[0].url) df

Output:

masterPortfolioId	secIds	…	defaultHoldingTypeCode	weight
1356725	F00000WK3T	…	E	11.16649
1356725	F00000WK3T	…	E	10.49672
…

morningstar_data.get_task_status( job_id: str, ) → MdapiTask#

Retrieves the status of an asynchronous task given its ID.

Parameters:

job_id (str) – The unique identifier of the asynchronous task.

Returns:

MdapiTask: An object representing the status and details of the asynchronous task.

The MdapiTask object contains the following attributes:

id: Unique identifier for the task
poll_url: URL endpoint for polling the task status
status: Current status of the task (SUCCESS, PENDING, or FAILURE)
result (Optional[TaskResult]): Contains the task results. This field is an object of type TaskResult, which contain below attributes. - dataframe_file_url - columns_with_list_values - warning_messages - pages: A list of Page objects representing paginated data. Each Page object contains below fields.
- url: Pass this URL to get_holdings_task_result to fetch a dataframe for this page. The URL expires after a certain period (see expiry_time below).
- id: Page number
- expiry_time: Expiry time of the URL. After this time, the URL will no longer work.
error_class: Exception class name if the task failed
error_message: Error message if the task failed
task_timeout_seconds: Maximum time to wait for task completion

Example::

status = md.mdapi.get_task_status(‘10000000-0000-0000-0000-000000000000’) status

Output:

MdapiTask object with task status and details:

MdapiTask(
    id='10000000-0000-0000-0000-000000000000',
    poll_url='https://datalab.morningstar.com/v1/task/10000000-0000-0000-0000-000000000000',
    status='success',
    result=TaskResult(
        dataframe_file_url='',
        columns_with_list_values=[],
        warning_messages=None,
        pages=[
                Page(
                    url='https://....',
                    id=1,
                    expiry_time='2025-10-17T16:48:07.932212814'
                )
            ]
    ),
    error_class=None,
    error_message=None,
    next_poll_delay_milliseconds=1,
    task_timeout_seconds=900
)