> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: 6cbbdb45-bd1a-47c4-9827-ce9f66e3c936 --- # Forecasts API > Learn how to retrieve forecast data from your HubSpot account. export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel}) => { const translations = { description: "Requires one of the following products or higher.", productNames: { marketing: "Marketing Hub", sales: "Sales Hub", service: "Service Hub", cms: "Content Hub", data: "Data Hub", commerce: "Revenue Hub" }, tiers: { free: "Free", starter: "Starter", professional: "Professional", enterprise: "Enterprise" } }; const translateTier = tier => { if (!tier) return ''; const lowerTier = tier.toLowerCase(); return translations.tiers[lowerTier] || tier; }; const products = [{ name: marketing ? translations.productNames.marketing : '', level: translateTier(marketingLevel), icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg", alt: "Marketing Hub" }, { name: sales ? translations.productNames.sales : '', level: translateTier(salesLevel), icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg", alt: "Sales Hub" }, { name: service ? translations.productNames.service : '', level: translateTier(serviceLevel), icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg", alt: "Service Hub" }, { name: cms ? translations.productNames.cms : '', level: translateTier(cmsLevel), icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg", alt: "Content Hub" }, { name: data ? translations.productNames.data : '', level: translateTier(dataLevel), icon: "https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/subscription_key_icons/operations_icon.svg", alt: "Data Hub" }, { name: commerce ? translations.productNames.commerce : '', level: translateTier(commerceLevel), icon: "https://developers.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg", alt: "Revenue Hub" }].filter(product => product.name && product.level); if (products.length === 0) return null; return
{translations.description}
{products.map((product, index) =>
{product.alt} {product.name} - {product.level}
)}
; }; This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback. The [forecast tool](https://knowledge.hubspot.com/forecast/use-the-forecast-tool) in HubSpot allows you track your team's progress towards customized sales or service targets. You can then use the forecasts API to retrieve data from existing forecasts you've created in your HubSpot account. **Please note:** this phase of the beta provides read-only endpoints for your forecasts. You cannot currently create, update, or delete forecasts using this API. ## Scope requirements To use the forecast endpoints, you'll need to authorize the `crm.objects.forecasts.read` scope for your app. ## Retrieve forecast data To retrieve all forecast submissions in your account, make a `GET` request to `/crm/objects/v3/forecasts` and provide any comma-separated properties that you want included in the response using the `?properties` query parameter. For example, a `GET` request to `https://api.hubspot.com/crm/objects/v3/forecasts?properties=hs_created_by_user_id,hs_milestone,hs_team_id,hs_year,hs_included_deal_ids` would result in a response that resembles the following: ```json theme={null} { "results": [ { "id": "475911884905", "properties": { "hs_created_by_user_id": "2620022", "hs_createdate": "2025-10-10T19:42:51.001Z", "hs_lastmodifieddate": "2025-10-14T16:52:43.757Z", "hs_milestone": "monthly", "hs_object_id": "475911884905", "hs_included_deal_ids": "29006642075;29051583857", "hs_team_id": "39577840", "hs_year": "2025" }, "createdAt": "2025-10-10T19:42:51.001Z", "updatedAt": "2025-10-14T16:52:43.757Z", "archived": false } ] } ``` You can also retrieve a specific forecast by its ID by making a `GET` request to `crm/objects/v3/forecasts/{id}`. The table below provides some common properties you might want to query for when using these APIs. | Property | Type | Description | | --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `hubspot_owner_id` | String | The owner ID for user-level forecasts. | | `hs_amount` | Number | The forecasted revenue amount for this submission. | | `hs_created_by_user_id` | String | The ID of the HubSpot user who created the forecast. You can use this [user provisioning endpoint](/api-reference/legacy/account/settings/user-provisioning/users/get-users) to get user data from your account. | | `hs_deal_pipeline_id` | String | The ID of the specific [pipeline](https://knowledge.hubspot.com/object-settings/set-up-and-customize-pipelines) set up for the forecast. This field will be `null` if *All pipelines* was selected when you submitted your forecast. | | `hs_fiscal_month` | String | The month number (1-12) for monthly forecasts, if applicable. | | `hs_fiscal_quarter` | String | The fiscal quarter (1-4) for quarterly forecasts, if applicable. | | `hs_forecast_fiscal_offset` | String | The start month offset to the fiscal year (e.g., `0` = January, `1` = February, etc). | | `hs_forecast_start_date` | String | Start date of the forecast, provided as a Unix timestamp (in milliseconds). | | `hs_forecast_end_date` | String | End date of the forecast, provided as a Unix timestamp (in milliseconds). | | `hs_forecast_type` | String | The ID of the forecast type being used. This value will be set to `0` or `null` for the default forecast type. To retrieve the forecast types available in your account, check out the [section below](#retrieve-forecast-types). | | `hs_is_all_pipelines` | String | A boolean that indicates whether the forecast applies to all pipelines. | | `hs_milestone` | String | An enumeration that denotes the period for which a forecast is submitted. Values include `monthly`, `quarterly`, or `yearly`. | | `hs_submission_notes` | String | Optional notes provided by the submitter. | | `hs_included_deal_ids` | String | A string that includes a semicolon-delimited list of submitted deals. | | `hs_team_id` | String | The ID of the contributing team, if applicable. You can use this [user provisioning endpoint](/api-reference/legacy/account/settings/user-provisioning/teams/get-teams) to get team data from your account. | | `hs_year` | String | The forecast's year. | ## Retrieve forecast types Forecast types define how HubSpot calculates and displays revenue projections in the [forecasting tool](https://knowledge.hubspot.com/forecast/use-the-forecast-tool). Each forecast type requires two properties: * **Amount property**: the aggregate value used in the forecast (e.g., a deal amount, ARR, or a custom revenue field). * **Date property**: the time-based field to use for filtering (e.g., a close date or a custom date property). Every HubSpot account has a default forecast type that uses the standard `amount` and `closedate` deal properties. You can create up to four additional custom forecast types to forecast on different revenue metrics, such as forecasting on a *Services Amount* property for one-time or ongoing professional services revenue. * When you create a custom forecast type, HubSpot automatically generates the supporting calculated properties to provide multi-currency support and probability-weighted projections. * If your account has [deal splits](https://knowledge.hubspot.com/deals/split-deal-revenue-credit-between-users) enabled, a matching set of properties will also be created on the deal split object. To retrieve all forecast types available in your account, make a `GET` request to `/forecast-settings/v3/forecast-types`. The response always includes the default "Sales Forecast" type (with `"id": "0"`) as the first item, followed by any custom forecast types you've configured. For example, to get all available forecast types, you'd make a `GET` request to `https://api.hubspot.com/forecast-settings/v3/forecast-types`. A successful response will resemble the following: ```json theme={null} { "results": [ { "forecastName": "Sales Forecast", "objectTypeId": "0-3", "amountProperty": "amount", "dateProperty": "closedate", "amountInHomeCurrencyProperty": "amount_in_home_currency", "weightedAmountInHomeCurrencyProperty": "hs_projected_amount_in_home_currency", "weightedAmountProperty": "hs_projected_amount", "dealSplitProperties": { "dealCustomAmountProperty": "hs_deal_amount", "dealCustomDateProperty": "hs_deal_close_date", "dealCustomAmountPropertyInHomeCurrency": "hs_deal_amount_in_home_currency", "dealSplitCustomAmountProperty": "hs_deal_split_amount", "dealSplitCustomAmountPropertyInHomeCurrency": "hs_deal_split_amount_in_home_currency", "dealSplitWeightedCustomAmountProperty": "hs_deal_split_projected_amount", "dealSplitWeightedCustomAmountPropertyInHomeCurrency": "hs_deal_split_projected_amount_in_home_currency" }, "updatedTimestamp": 1760124698903, "createdAtTimestamp": 1760124698903, "forecastTypeId": 0, "updatedBy": 0, "createdBy": 0, "amountOrDatePropertyRestrictedForUser": false, "id": "0", "updatedAt": "2025-10-10T19:31:38.903Z", "createdAt": "2025-10-10T19:31:38.903Z", "defaultType": true }, { "forecastName": "joe forecast", "objectTypeId": "0-3", "amountProperty": "amount", "dateProperty": "closedate", "amountInHomeCurrencyProperty": "amount_in_home_currency", "weightedAmountInHomeCurrencyProperty": "hs_projected_amount_in_home_currency", "weightedAmountProperty": "hs_projected_amount", "dealSplitProperties": null, "updatedTimestamp": 1760124698903, "createdAtTimestamp": 1760124698903, "forecastTypeId": 16142707, "updatedBy": 2620022, "createdBy": 2620022, "amountOrDatePropertyRestrictedForUser": false, "id": "16142707", "updatedAt": "2025-10-10T19:31:38.903Z", "createdAt": "2025-10-10T19:31:38.903Z", "defaultType": false } ] } ``` You can also retrieve a specific forecast type by its ID by making a `GET` request to `/forecast-settings/v3/forecast-types/{id}`. To retrieve the default forecast type, use `0` as the ID. The table below provides the properties available for each forecast type: | Property | Type | Description | | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `objectTypeId` | String | The CRM object type this forecast applies to. Currently only deals (`0-3`) are supported. | | `amountInHomeCurrencyProperty` | String | The property containing the amount converted to the account's home currency. For multi-currency accounts, this enables consistent aggregation across deals in different currencies. | | `updatedAt` | String | The date when the forecast type was last updated (as an ISO 8601 date). | | `updatedBy` | Number | The ID of the HubSpot user who last updated the type. | | `weightedAmountProperty` | String | The property containing the amount multiplied by the deal's win probability. Used to calculate probability-weighted pipeline projections. | | `updatedTimestamp` | Number | The date when the forecast type was last updated (as a Unix timestamp in milliseconds). | | `defaultType` | Boolean | Whether this is the account's default forecast type. The default type uses the standard `amount` and `closedate` properties and cannot be deleted. | | `createdAt` | String | The date when the forecast type was last created (as an ISO 8601 date). | | `dealSplitProperties` | Object | When deal splits are enabled, contains the corresponding deal split object properties for amount, date, and currency calculations. `null` if deal splits are not configured. | | `createdAtTimestamp` | Number | The date when the forecast type was created (as a Unix timestamp in milliseconds). | | `amountProperty` | String | The deal property used as the revenue value for forecasting (e.g., `amount`, `arr`, or a custom currency property). This is the primary value that gets rolled up in forecast views. | | `createdBy` | Number | The ID of the HubSpot user who created the type. | | `forecastTypeId` | Number | The ID of the forecast type (represented as a number). | | `dateProperty` | String | The deal property used to determine which time period a deal falls into (e.g., `closedate` or a custom date property). Deals are included in a forecast period based on this date. | | `id` | String | The ID of the forecast type. | | `amountOrDatePropertyRestrictedForUser` | Boolean | A boolean that indicates whether any of the properties in forecast type is restricted for users who aren't [super admins](https://knowledge.hubspot.com/user-management/hubspot-user-permissions-guide#super-admin). If `true`, these users won't be able to access this forecast type. | | `forecastName` | String | The name of the forecast type. | | `weightedAmountInHomeCurrencyProperty` | String | The name of the property used to calculate the weighted amount in the account's home currency. | ### Deal split properties When [deal splits](https://knowledge.hubspot.com/deals/split-deal-revenue-credit-between-users) are enabled for an account, the returned forecast type includes a populated `dealSplitProperties` object. Deal splits allow a single deal's revenue to be divided among multiple owners based on percentages. Because deal splits are stored as a separate [CRM object type](https://app.hubspot.com/myaccounts?next=developerdocs\&redirect=%2Fapi-reference%2Fcrm-deal-splits-v3%2Fguide), forecasts require additional properties to aggregate split amounts correctly. The `dealSplitProperties` property in the response maps the forecast type's amount and date properties to their corresponding deal split equivalents. Based on whether the forecast type is aggregated from the deal object or the deal split object, the following properties are provided within `dealSplitProperties`: **Deal related properties** The following properties are used when aggregating from the deal object: | Property | Type | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | | `dealCustomAmountProperty` | String | The calculated property on the deal object that stores the custom amount value. Used as the source for deal split calculations. | | `dealCustomDateProperty` | String | The date property on the deal object used for time-based filtering. Typically matches the forecast type's `dateProperty`. | | `dealCustomAmountPropertyInHomeCurrency` | String | The calculated property on the deal object containing the custom amount converted to home currency. | **Deal split related properties** The following properties are used when aggregating from the deal split object: | Property | Type | Description | | ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `dealSplitCustomAmountProperty` | String | The property on the deal split object containing each owner's portion of the custom amount (amount \* split percentage). | | `dealSplitCustomAmountPropertyInHomeCurrency` | String | The property on the deal split object containing each owner's portion converted to home currency. | | `dealSplitWeightedCustomAmountProperty` | String | The property on the deal split object containing each owner's portion multiplied by win probability. | | `dealSplitWeightedCustomAmountPropertyInHomeCurrency` | String | The property on the deal split object containing each owner's weighted portion in home currency. | If a HubSpot user views their individual forecast with deal splits enabled: * HubSpot will query the corresponding `deal_split` object instead of the `deal` object. * HubSpot will use the `dealSplitCustomAmountProperty` field to get each sales rep's portion of the revenue. * Currency conversion will use the value defined in the `dealSplitCustomAmountPropertyInHomeCurrency` field. * Weighted projections will use the value defined in either the `dealSplitWeightedCustomAmountProperty` or `dealSplitWeightedCustomAmountPropertyInHomeCurrency` fields. This behavior ensures that when a \$100,000 deal is split 60/40, one sales rep will see \$60,000 in their forecast, while the other rep will see \$40,000, rather than both seeing the full \$100,000. The code block below provides an example response from making a `GET` request to `/forecast-settings/v3/forecast-types` with the `dealSplitProperties` property populated: ```json theme={null} { "results": [ { "forecastName": "Net New ARR Forecast", "objectTypeId": "0-3", "amountProperty": "net_new_arr", "dateProperty": "closedate", "amountInHomeCurrencyProperty": "hs_net_new_arr_in_home_currency", "weightedAmountInHomeCurrencyProperty": "hs_weighted_net_new_arr_in_home_currency", "weightedAmountProperty": "hs_weighted_net_new_arr", "dealSplitProperties": { "dealCustomAmountProperty": "hs_net_new_arr", "dealCustomDateProperty": "closedate", "dealCustomAmountPropertyInHomeCurrency": "hs_net_new_arr_in_home_currency", "dealSplitCustomAmountProperty": "hs_deal_split_net_new_arr", "dealSplitCustomAmountPropertyInHomeCurrency": "hs_deal_split_net_new_arr_in_home_currency", "dealSplitWeightedCustomAmountProperty": "hs_deal_split_weighted_net_new_arr", "dealSplitWeightedCustomAmountPropertyInHomeCurrency": "hs_deal_split_weighted_net_new_arr_in_home_currency" }, "forecastTypeId": 16272973, "id": "16272973", "defaultType": false, "amountOrDatePropertyRestrictedForUser": false, "createdBy": 2620022, "updatedBy": 2620022, "createdAt": "2025-09-15T14:22:10.000Z", "updatedAt": "2025-09-15T14:22:10.000Z", "createdAtTimestamp": 1726409930000, "updatedTimestamp": 1726409930000 } ] } ```