## 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:

```json
{
  "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

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