ConnectCloud Developers

Read the flow metrics of a project (tenant:forge:read)

GET /api/forge/v1/projects/{key}/metrics

Module: Forge · operationId: getForgeProjectMetrics · Tag: Metrics · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read and a project the caller sees. from and to are dates (UTC, both inclusive); without them the range is the last 12 weeks, a range over 52 weeks is 400 invalid on to, from after to 400 on from. Weeks start on Monday (UTC). Only items done now count; they count in the week they last entered a done status. Cycle time runs from first entering an active status to that moment (items that never were active are left out), lead time from creation. Categories of past statuses are the statuses' current categories. openByCategory counts the items now in triage, todo, active and on_hold; velocity lists the iterations closed in the range from their snapshots.

Parameters

Name In Type Required Description
from query string (date) First day, YYYY-MM-DD
to query string (date) Last day, YYYY-MM-DD
key path string yes Project key (e.g. APP)

Responses

  • 200 The metrics (application/json)
  • 400 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • cycleTime (DurationStats, required)
    • count (integer, required): Number of items measured
    • medianHours (number, nullable, required): Nearest-rank median; null without values
    • p85Hours (number, nullable, required): Nearest-rank 85th percentile; null without values
  • from (string (date), required): First day of the range (inclusive, UTC)
  • leadTime (DurationStats, required)
    • count (integer, required): Number of items measured
    • medianHours (number, nullable, required): Nearest-rank median; null without values
    • p85Hours (number, nullable, required): Nearest-rank 85th percentile; null without values
  • openByCategory (object, required): Open items per status category now
    • active (integer, required): Items in progress
    • on_hold (integer, required): Items on hold
    • todo (integer, required): Items in todo
    • triage (integer, required): Items in triage
  • throughput (array of object, required): Items finished per week (UTC, Monday first); every week of the range is present
    • count (integer, required): Items finished in the week
    • weekStart (string (date), required): Monday of the week
  • to (string (date), required): Last day of the range (inclusive, UTC)
  • velocity (array of object, required): Closed iterations with their figures
    • closedAt (string (date-time), nullable, required): When it was closed
    • committed (number, nullable, required): Estimate committed at the start
    • doneEstimate (number, required): Estimate of the items done at the close
    • doneItems (integer, required): Items done at the close
    • endsOn (string (date), required): Last day of the iteration
    • iterationId (string (uuid), required): Iteration id
    • name (string, required): Iteration name
    • startsOn (string (date), required): First day of the iteration
    • totalItems (integer, required): Items in the iteration at the close

Example 200 answer:

{
  "cycleTime": {
    "count": 14,
    "medianHours": 54.5,
    "p85Hours": 166
  },
  "from": "2026-08-31",
  "leadTime": {
    "count": 15,
    "medianHours": 141.2,
    "p85Hours": 402.5
  },
  "openByCategory": {
    "active": 3,
    "on_hold": 0,
    "todo": 4,
    "triage": 1
  },
  "throughput": [
    {
      "count": 0,
      "weekStart": "2026-08-31"
    },
    {
      "count": 0,
      "weekStart": "2026-09-07"
    },
    {
      "count": 0,
      "weekStart": "2026-09-14"
    },
    {
      "count": 0,
      "weekStart": "2026-09-21"
    },
    {
      "count": 1,
      "weekStart": "2026-09-28"
    },
    {
      "count": 1,
      "weekStart": "2026-10-05"
    },
    {
      "count": 2,
      "weekStart": "2026-10-12"
    },
    {
      "count": 3,
      "weekStart": "2026-10-19"
    },
    {
      "count": 2,
      "weekStart": "2026-10-26"
    },
    {
      "count": 3,
      "weekStart": "2026-11-02"
    },
    {
      "count": 3,
      "weekStart": "2026-11-09"
    },
    {
      "count": 0,
      "weekStart": "2026-11-16"
    }
  ],
  "to": "2026-11-18",
  "velocity": [
    {
      "closedAt": "2026-11-04T08:30:00Z",
      "committed": 21,
      "doneEstimate": 18,
      "doneItems": 6,
      "endsOn": "2026-11-03",
      "iterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d01",
      "name": "Iteration 1 – Anmeldung",
      "startsOn": "2026-10-14",
      "totalItems": 7
    }
  ]
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/metrics' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI