Work with Results

When you submit a request, the API processes it as a job. This page explains how to check the job, retrieve the results when they are ready, and read the response.

Check the Job

The 202 response to your request contains a link for checking the job.

"_links": {
  "href": "https://www.us-api.morningstar.com/dynamic-services-apis/jobs/16bf1a7a-c883-4424-8810-2f4e9d244d40",
  "rel": "status",
  "method": "GET"
}

Call the link with your access token until the job is complete.

curl --request GET \
  --url "https://www.us-api.morningstar.com/dynamic-services-apis/jobs/16bf1a7a-c883-4424-8810-2f4e9d244d40" \
  --header "Authorization: Bearer {token}"

Don't call the link continuously. Wait between calls, and stop when the job is complete.

Retrieve the Results

When the job is complete, use its result ID to retrieve the results.

GET /direct-web-services/v1/investments/result/{resultId}

The following request retrieves the results.

curl --request GET \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments/result/{resultId}" \
  --header "accept: application/json" \
  --header "Authorization: Bearer {token}"

Use the base URL for your region, as described in Getting Started. The request takes no query parameters or body.

Read the Response

The response has two top-level properties.

The following response is for a request for the enterprise value and profitability data of one investment.

{
  "investments": [
    {
      "identifiers": {
        "performanceId": "0P00000046"
      },
      "enterpriseValueCalculations": [
        {
          "asOfDate": "2025-09-03",
          "analystNormalizedEnterpriseValueToEbitdaRatio": 21.70188,
          "analystNormalizedEnterpriseValueToEbitRatio": 61.69785
        }
      ],
      "profitability": [
        {
          "reportPeriodEndDate": "2025-03-31",
          "analystNormalizedEbit": 10914000,
          "analystNormalizedEbitda": 50354000,
          "currencyCode": {
            "value": "US Dollar",
            "code": "USD"
          }
        }
      ]
    }
  ],
  "metadata": {
    "requestId": "7ccd91c0-6146-4256-8aba-3a1f2e5d0203",
    "time": "2025-11-08T13:18:30.5777168Z"
  }
}

The example is shortened. A real response has all the data points in the views you requested.

Investments

Each object in investments is one investment. It has the following characteristics.

• 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, such as profitability and trailingReturn. 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.

Check Metadata and Warnings

The metadata object has the following properties.

A successful response doesn't guarantee that every investment returned data. Check messages in every response. Each message has the following properties.

Each object in investments can have the following properties.

If an identifier couldn't be matched, check it for typos, check that idType matches it, and check the lookup details. If you aren't entitled to a data point, contact your Morningstar account manager.

Handle Errors

A request that fails returns an error response instead of results.

If the response payload is too large, split the request into smaller requests, with fewer investments or a shorter date range.

For the meaning of each error code, see Error Messages. For help with common problems, see Troubleshooting.