[API] Fetch Goal Progress (KPI Value) via goals API

HubSpot Ideas

Status: Idea Submitted

1

Problem: HubSpot’s “Goals” feature is invaluable for tracking progress against key metrics within the platform. However, accessing the real-time “KPI value” (the current progress or achievement against a goal) programmatically via the API is currently complex and inefficient.

To determine a goal’s current performance, developers must:

  1. Fetch the goal’s definition (start/end dates, object type, criteria, measured properties).
  2. Independently query the underlying CRM objects (e.g., Deals, Contacts) using filters derived from the goal’s definition.
  3. Manually aggregate and calculate the current KPI value based on these raw object properties.

This approach presents several challenges:

  • Increased Development Time & Complexity: Developers need to reverse-engineer goal logic, interpret hs_goal_criteria JSON, and manage complex search requests for each goal type.
  • Performance Overhead & Rate Limit Concerns: Fetching and processing potentially thousands of underlying CRM objects per goal can be slow and quickly consume API rate limits, especially when monitoring multiple goals.
  • Potential for Inaccuracy: Manual calculation introduces a risk of misinterpreting goal criteria, leading to discrepancies between API-derived values and what’s shown in the HubSpot UI.
  • Redundant Logic: HubSpot already calculates and displays these values in the UI, suggesting the underlying logic and data are readily available internally.

Proposed Solution: We request a new, dedicated API endpoint (or an extension to the existing CRM Objects API for goal_targets) that allows developers to directly retrieve the current, real-time “KPI value” or progress for a given Goal ID.

Proposed Endpoint/Extension (Conceptual):

GET /crm/v3/objects/goal_targets/{goalId}/performance

Expected Response (Conceptual):

JSON

{
 "goalId": "234567890",
 "goalName": "Q3 Revenue Target",
 "targetAmount": 100000.00,
 "currentKpiValue": 75500.50,
 "progressPercentage": 75.50,
 "status": "On Track", // Optional: derived status (On Track, Behind, Achieved)
 "lastCalculatedAt": "2025-07-31T14:30:00Z" // Timestamp of last calculation
}

Alternatively, extending the existing GET /crm/v3/objects/goal_targets/{goalId} endpoint to include a performance or current_kpi_value property would also be highly beneficial.