Retrieve Delta Dates

View Markdown Download Markdown

The delta dates endpoint tells you which data points changed for your investments in a period, and on which dates. Use it to decide whether a delta load is needed. This page explains how to send a request and read the response. For background, see Delta Loads.

Delta dates currently apply to the equity-financials view only.

Request Overview

To retrieve delta dates, send a POST request to the delta dates endpoint.

POST /direct-web-services/v1/investments/deltas

Use the base URL for your region, as described in Getting Started. The request must include the following headers.

Header	Value
`Authorization`	`Bearer {token}`. See Authentication.
`Content-Type`	`application/json`

Unlike a request for investment details, this request doesn't use the Prefer header. The response is returned immediately and isn't processed as a job.

Build the Request

The body has the following properties.

Property	Required	Description
`investments`	Yes	The investments to check, from 1 to 250. Each has an `id` and, optionally, an `idType` and lookup details.
`views`	Yes	The view to check. Use `equity-financials`, with the parameters that you use in your loads.
`deltaStartTime`	No	The start of the period to check, in UTC, for example `2026-05-01T09:06:55Z`.
`deltaEndTime`	No	The end of the period to check, in UTC.
`startDate` and `endDate`	No	The date range of the data, as `yyyy-MM-dd`.
`languageId` and `countryId`	No	The language and country, for data that depends on them.

Send the Request

The following request checks one investment for changes to financials data from 1 May 2026.

curl --request POST \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/investments/deltas" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "investments": [
      { "id": "F0GBR051V5", "idType": "securityId" }
    ],
    "views": [
      {
        "viewId": "equity-financials",
        "parameters": {
          "reportType": ["a"],
          "period": ["a"],
          "numberOfMonths": ["3"],
          "segmentType": ["Business"]
        }
      }
    ],
    "deltaStartTime": "2026-05-01T09:06:55Z",
    "startDate": "2025-08-30",
    "endDate": "2026-07-10"
  }'

Read the Response

The response has an investments array and a metadata object.

{
  "investments": [
    {
      "growthRates": [
        {
          "dataPointId": "businessRevenue3YearGrowth",
          "primaryKeys": {
            "reportType": "R",
            "numberOfMonths": "3"
          },
          "deltas": [
            { "date": "2023-06-30" }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "requestId": "c2f10658-3bfd-457c-96d6-25c05766cb76",
    "time": "2025-11-07T16:03:54.6113241Z"
  }
}

Each object in investments is one investment. Its properties are data groups, such as growthRates, profitability and valuation. Which groups are present depends on the data points that changed.

Each data group is an array, with one entry for each data point that changed.

Property	Description
`dataPointId`	The data point that changed.
`primaryKeys`	The keys that identify the record that changed, for example `reportType` and `numberOfMonths`.
`deltas`	The dates for the change. Each has a `date`.

Use the Response

Decide whether to load. If no data points changed, you don't need a delta load for that investment.
Plan the load. The data groups and data points tell you which part of your stored data is affected.
Run the delta load. Use the same views and parameters, with deltaStartTime set to the start of the period. See Request Delta Load.

Errors

Error Code	Message
`400.investmentDetailsAsync.033`	Invalid delta date format. Dates must be ISO 8601 UTC format, e.g. 2025-02-07T19:06:55Z.
`400.investmentDetailsAsync.034`	The deltaStartTime value cannot be later than the deltaEndTime value. Please input a valid value.
`400.investmentDetailsAsync.010`	The startDate value cannot be later than the endDate value. Please input a valid value.
`400.investmentDetailsAsync.032`	Invalid date format. Dates must be formatted as YYYY-MM-DD.

For the full list, see Error Messages.