OKR Progress Calculator

Overview

You send the key results — a metric moving from a start toward a target, a milestone that is done or not, or a figure that is already a proportion — and we return each one's progress, the weighted objective progress, the percentage and the status band it falls in. Progress is defined rather than guessed: a metric is the distance travelled from start to target, which is why the two must differ, and a target below the start reads correctly for a metric you want to bring down. Overshoot and backsliding are clamped to nothing-to-fully-done by default and flagged where they happened, so a key result at 120 per cent cannot carry an objective past complete. Every contribution is shown and they add up to exactly the progress beside them.

Every OKR tool computes progress, and no two agree on how. The disagreements are always the same three: whether a metric's progress is measured from zero or from where it started, what a key result at 120 per cent does to the objective, and where 'behind' ends and 'on track' begins. Each of those is an explicit input here, and the answer comes back with the arithmetic and the boundaries attached, which is what makes two teams' numbers comparable.

When to use it

Scope

Non-goals

• Does not write the objectives or the key results, and does not judge whether they are good ones
• Does not read a metric from anywhere: current is a number you send
• Does not forecast, and does not compare this quarter with the last one
• Does not store progress or notify anybody about it

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"business.okr_progress","input":{"keyResults":[{"id":"kr1","type":"METRIC","start":0,"target":100,"current":40}]}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("business.okr_progress", {"keyResults":[{"id":"kr1","type":"METRIC","start":0,"target":100,"current":40},{"current":1,"type":"MILESTONE","id":"kr2"},{"current":0.25,"type":"PERCENT","id":"kr3"}],"objective":{"id":"OBJ-1"}});

Errors

Other limits

Limitations

• Does not write the objectives or the key results, and does not judge whether they are good ones
• Does not read a metric from anywhere: current is a number you send
• Does not forecast, and does not compare this quarter with the last one
• Does not store progress or notify anybody about it
• Deriving current from a data source — fetch it first, then send it
• Scoring or ranking things, which is business.priority_score and business.decision_matrix
• Objectives with more than 200 key results, which is a planning problem

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "business.okr_progress",
  "input": {
    "keyResults": [
      {
        "id": "kr1",
        "type": "METRIC",
        "start": 0,
        "target": 100,
        "current": 40
      },
      {
        "current": 1,
        "type": "MILESTONE",
        "id": "kr2"
      },
      {
        "current": 0.25,
        "type": "PERCENT",
        "id": "kr3"
      }
    ],
    "objective": {
      "id": "OBJ-1"
    }
  }
}

Examples

{
  "keyResults": [
    {
      "id": "kr1",
      "type": "METRIC",
      "start": 0,
      "target": 100,
      "current": 40
    },
    {
      "current": 1,
      "type": "MILESTONE",
      "id": "kr2"
    },
    {
      "current": 0.25,
      "type": "PERCENT",
      "id": "kr3"
    }
  ],
  "objective": {
    "id": "OBJ-1"
  }
}

{
  "progressPercent": 55,
  "weightMode": "EQUAL",
  "statusBands": [
    {
      "id": "AT_RISK",
      "label": "At risk",
      "from": 0,
      "to": 0.4
    },
    {
      "id": "BEHIND",
      "label": "Behind",
      "from": 0.4,
      "to": 0.7
    },
    {
      "id": "ON_TRACK",
      "label": "On track",
      "from": 0.7,
      "to": 1
    }
  ],
  "progress": 0.55,
  "status": "BEHIND",
  "statusLabel": "Behind",
  "objectiveId": "OBJ-1",
  "keyResults": [
    {
      "id": "kr1",
      "type": "METRIC",
      "progress": 0.4,
      "weight": 1,
      "normalizedWeight": 0.3333,
      "contribution": 0.1333,
      "clamped": false
    },
    {
      "id": "kr2",
      "type": "MILESTONE",
      "progress": 1,
      "weight": 1,
      "normalizedWeight": 0.3333,
      "contribution": 0.3333,
      "clamped": false
    },
    {
      "id": "kr3",
      "type": "PERCENT",
      "progress": 0.25,
      "weight": 1,
      "normalizedWeight": 0.3333,
      "contribution": 0.0834,
      "clamped": false
    }
  ]
}

{
  "keyResults": [
    {
      "id": "churn",
      "type": "METRIC",
      "start": 5,
      "target": 3,
      "current": 2.5,
      "weight": 3,
      "direction": "DECREASE"
    },
    {
      "id": "nps",
      "type": "METRIC",
      "start": 30,
      "target": 50,
      "current": 35,
      "weight": 1
    }
  ],
  "objective": {
    "id": "OBJ-CHURN",
    "weightMode": "WEIGHTED"
  }
}

{
  "progressPercent": 81.25,
  "weightMode": "WEIGHTED",
  "statusBands": [
    {
      "id": "AT_RISK",
      "label": "At risk",
      "from": 0,
      "to": 0.4
    },
    {
      "id": "BEHIND",
      "label": "Behind",
      "from": 0.4,
      "to": 0.7
    },
    {
      "id": "ON_TRACK",
      "label": "On track",
      "from": 0.7,
      "to": 1
    }
  ],
  "progress": 0.8125,
  "status": "ON_TRACK",
  "statusLabel": "On track",
  "objectiveId": "OBJ-CHURN",
  "keyResults": [
    {
      "id": "churn",
      "type": "METRIC",
      "progress": 1,
      "weight": 3,
      "normalizedWeight": 0.75,
      "contribution": 0.75,
      "clamped": true,
      "note": "CLAMPED_HIGH"
    },
    {
      "id": "nps",
      "type": "METRIC",
      "progress": 0.25,
      "weight": 1,
      "normalizedWeight": 0.25,
      "contribution": 0.0625,
      "clamped": false
    }
  ]
}

Recommended use cases

• Compute objective progress the same way for every team, from figures they already have
• Mix a metric, a milestone and an already-percentage key result under one objective
• Weight a key result that carries most of the objective without hiding the arithmetic
• Publish the status band and its boundaries together, so nobody argues about 'behind'

Avoid for

• Deriving current from a data source — fetch it first, then send it
• Scoring or ranking things, which is business.priority_score and business.decision_matrix
• Objectives with more than 200 key results, which is a planning problem

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags