## Pipeline report (tenant:crm:read)

`GET /api/crm/v1/reports/pipeline`

Module: CRM · operationId: `getPipelineReport` · Tag: Reports · Auth: access token (`Authorization: Bearer <accessToken>`)

The open pipeline per stage, the forecast per month (by expected close date, Europe/Berlin), the
pipeline per owner, and win rate, average deal size and days to close of the opportunities closed
between `from` and `to` (default the last 12 months).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string (date-time) |  |  |
| `to` | query | string (date-time) |  |  |
| `owner` | query | string |  | Only records of this owner (e-mail address), or `me` for the calling person. (max length 255) |

### Responses

- **200** Report (`application/json`)
- **400** Invalid input (`invalid`): `field` names the first invalid field, `details.fields` every one (JSON paths for
bodies, parameter names for the query). Some refusals have their own code (`invalid_sort`,
`invalid_stages`, `invalid_custom_fields`, `convert_target_required`, `invalid_csv`, …).
 (`application/json`)
- **401** Missing, invalid or expired token (no body).
- **403** The token lacks the permission (`insufficient permissions`) or has no active tenant.
 (`application/json`)
- **500** Unexpected error; details are only logged. (`application/json`)

Fields of the 200 answer:

- `averageDaysToClose` (number (double), nullable, required): Average days from creation to close of the won opportunities; `null` without won opportunities.
- `averageDealSize` (number (double), nullable, required): Average won value per won opportunity; `null` without won opportunities.
- `byOwner` (array of object, required): Open pipeline and won value per owner.
  - `count` (integer, required): Open opportunities of the owner.
  - `ownerEmail` (string, required): Empty for opportunities without owner.
  - `value` (number (double), required): Their value.
  - `weighted` (number (double), required): Their value times probability.
  - `wonValue` (number (double), required): Value won in the period.
- `byStage` (array of object, required): Open pipeline per open stage.
  - `count` (integer, required): Open opportunities in the stage.
  - `key` (string, required): Stage key.
  - `label` (string, required): Stage label.
  - `value` (number (double), required): Their value.
  - `weighted` (number (double), required): Value times probability.
- `forecast` (array of object, required): Open and won value per month.
  - `month` (string, required): YYYY-MM (Europe/Berlin).
  - `value` (number (double), required): Open value by expected close date.
  - `weighted` (number (double), required): Open value times probability.
  - `wonValue` (number (double), required): Value won in the month.
- `from` (string (date-time), required): Start of the period.
- `lost` (integer, required): Opportunities lost in the period.
- `to` (string (date-time), required): End of the period.
- `winRate` (number (double), nullable, required): won / (won + lost); `null` without closed opportunities.
- `won` (integer, required): Opportunities won in the period.
- `wonValue` (number (double), required): Value of the opportunities won in the period: the net total of the orders trade reported for an opportunity (newest revision per order, cancelled ones left out), else its own value.

Example 200 answer:

```json
{
  "averageDaysToClose": 38.5,
  "averageDealSize": 13750,
  "byOwner": [
    {
      "count": 4,
      "ownerEmail": "lena.vogel@muster-it.example",
      "value": 39900,
      "weighted": 14350,
      "wonValue": 9600
    },
    {
      "count": 1,
      "ownerEmail": "felix.neumann@muster-it.example",
      "value": 12000,
      "weighted": 3000,
      "wonValue": 0
    }
  ],
  "byStage": [
    {
      "count": 3,
      "key": "PROSPECTING",
      "label": "Erstkontakt",
      "value": 21500,
      "weighted": 2150
    },
    {
      "count": 2,
      "key": "PROPOSAL",
      "label": "Angebot",
      "value": 30400,
      "weighted": 15200
    }
  ],
  "forecast": [
    {
      "month": "2026-12",
      "value": 30400,
      "weighted": 15200,
      "wonValue": 9600
    }
  ],
  "from": "2026-01-01T00:00:00Z",
  "lost": 1,
  "to": "2026-12-31T23:59:59Z",
  "winRate": 0.75,
  "won": 3,
  "wonValue": 41250
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/crm/v1/reports/pipeline' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
