KPI

Get a KPI

This endpoint retrieves a specific KPI identified by its ID.

For convenience, some currently relevant values are included in the responses:

  • The current_actual is the actual value with the most recent date in the past.
  • The current_target and current_forecast are the target and forecast with the nearest date in the future. This allows building simple dashboards. For any more advanced visualization needs, query the KPI's values and work with the raw time series.

Some properties of the API response depend on the type of KPI:

  • For monetary type KPIs, the currency field will be included.
  • For percental and numeric type KPIs, the currency field is omitted.
  • If kpi.kind is team then team information will be included in the response.
  • If kpi.kind is business_unit then business_unit information will be included in the response.
get/kpis/{id}

Request

  • Base URL: https://connect.workpath.com/api/v3
  • URL: https://connect.workpath.com/api/v3/kpis/{id}
  • Auth: HTTP bearer

Headers

Content-Typestring required

application/json

Response

OK

idinteger

Unique identifier for the KPI.

titlestring

Concise, descriptive name of the KPI that highlights its primary focus or measurement.

kind'organization' | 'team' | 'business_unit'

Whether the KPI belongs to the whole organization (organization), a Business Unit (business_unit) or a team (team).

descriptionstring

A brief explanation of the KPI, providing context and relevance to its purpose or measurement.

external_idstring nullable

External system identifier for integration purposes.

decimal_placesinteger nullable

Number of decimal places the KPI value is shown with (0-10). null uses the default.

target_type'above' | 'below'

Whether higher values are better (above: the aim is to reach or exceed the target) or lower values are better (below: the aim is to stay at or under the target).

workpath_urlstring uri

URL to view the KPI in the Workpath platform.

created_atstring date-time

Timestamp when the KPI was created in ISO 8601 format.

updated_atstring date-time

Timestamp when the KPI was last updated in ISO 8601 format.

Example response

{
  "id": 10,
  "title": "Product Users: Quarterly Active Users Growth Rate.",
  "description": "Users that were online within the last 90 days, year over year.",
  "kind": "team",
  "target_type": "above",
  "external_id": "KPI-QAU-001",
  "decimal_places": 2,
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2026-03-02T09:15:00Z",
  "workpath_url": "https://acme.workpath.com/goals/overview/teams/23?selectedKpiId=10#kpis",
  "type": {
    "name": "percental"
  },
  "team": {
    "id": 23,
    "name": "Product Growth"
  },
  "owners": {
    "teams": [
      {
        "id": 23,
        "name": "Product Growth"
      }
    ]
  },
  "current_actual": {
    "value": 15.12,
    "date": "2026-03-01",
    "status": "On Track",
    "summary": "All looking good so far.",
    "status_color": "success"
  },
  "current_target": {
    "value": 40,
    "date": "2026-06-30"
  },
  "current_forecast": {
    "value": 42.43,
    "date": "2026-06-30"
  },
  "supports": {
    "kpis": [
      {
        "id": 8,
        "title": "Annual Recurring Revenue (ARR)"
      }
    ]
  },
  "supported_by": {
    "goals": [
      {
        "id": 55,
        "title": "Grow our user base by 50% this year"
      }
    ],
    "initiatives": [
      {
        "id": 12,
        "title": "Launch referral program for existing users"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.