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 measuredmedianHours(number, nullable, required): Nearest-rank median; null without valuesp85Hours(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 measuredmedianHours(number, nullable, required): Nearest-rank median; null without valuesp85Hours(number, nullable, required): Nearest-rank 85th percentile; null without values
openByCategory(object, required): Open items per status category nowactive(integer, required): Items in progresson_hold(integer, required): Items on holdtodo(integer, required): Items in todotriage(integer, required): Items in triage
throughput(array of object, required): Items finished per week (UTC, Monday first); every week of the range is presentcount(integer, required): Items finished in the weekweekStart(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 figuresclosedAt(string (date-time), nullable, required): When it was closedcommitted(number, nullable, required): Estimate committed at the startdoneEstimate(number, required): Estimate of the items done at the closedoneItems(integer, required): Items done at the closeendsOn(string (date), required): Last day of the iterationiterationId(string (uuid), required): Iteration idname(string, required): Iteration namestartsOn(string (date), required): First day of the iterationtotalItems(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"