# Metrics report (https://docs.pulsarml.com/v1/api-reference/reports/post-reports-metrics)

Return OEE, availability, quality and lost minutes per machine and shift.

Each row carries the shift indicators (available time, downtime split by cause) together
with the derived production metrics: `availability`, `effectiveness`, `quality`, `oee` and
`netOee`, plus minutes lost to low speed and to low quality.

A `POST` that only reads — the `reports.read` scope is sufficient. Prefer this over
deriving OEE from production logs: shift boundaries, downtime classification and counting
factors are already applied.

## `POST /v1/reports/metrics`

Base URLs:
- `https://draco.prod.pulsarml.com` — Production
- `https://draco.dev.pulsarml.com` — Development (sandbox)

Authentication: send your API key in the `x-api-key` header.

### Request body (`application/json`, required)

Type: object (`GetMetricsReportRequestV1`)

- `page` (integer, optional, default `1`, > 0, e.g. `1`) — The page number for pagination
- `limit` (integer, optional, default `10`, > 0, e.g. `10`) — The number of items per page for pagination
- `machines` (object, optional, nullable) — Filter criteria for machines
  - `search` (string, optional, nullable) — Search term for Machines
  - `include` (array of integer, optional, nullable) — Items to include by id
  - `exclude` (array of integer, optional, nullable) — Items to exclude by id
- `startDate` (object, optional, nullable) — Filter criteria for start date
  - `after` (string (date-time), optional, nullable) — Filter by after date
  - `before` (string (date-time), optional, nullable) — Filter by before date
  - `between` (object, optional, nullable) — Filter by date range
    - `start` (string (date-time), optional, nullable, e.g. `"2024-01-01T00:00:00.000Z"`) — Start date of the range
    - `end` (string (date-time), optional, nullable, e.g. `"2024-01-31T23:59:59.000Z"`) — End date of the range
  - `equal` (string (date-time), optional, nullable) — Filter by equal date
- `endDate` (object, optional, nullable) — Filter criteria for end date
  - `after` (string (date-time), optional, nullable) — Filter by after date
  - `before` (string (date-time), optional, nullable) — Filter by before date
  - `between` (object, optional, nullable) — Filter by date range
    - `start` (string (date-time), optional, nullable, e.g. `"2024-01-01T00:00:00.000Z"`) — Start date of the range
    - `end` (string (date-time), optional, nullable, e.g. `"2024-01-31T23:59:59.000Z"`) — End date of the range
  - `equal` (string (date-time), optional, nullable) — Filter by equal date

### Responses

#### 200 — A page of per-machine, per-shift metrics

Type: object (`GetMetricsReportResponseV1`)

- `totalCount` (integer, optional, default `100`) — The total count of items
- `totalPages` (integer, optional, default `10`) — The total number of pages
- `currentPage` (integer, optional, default `1`) — The current page
- `metrics` (array of object, required)
  - `company` (object, required) — The company associated with the metric report.
    - `id` (integer, required, e.g. `1`) — The unique identifier for the company.
    - `name` (string, required, e.g. `"company 1"`) — The name of the company.
  - `machine` (object, required) — The machine of the metric report.
    - `id` (integer, required, e.g. `1`) — The unique identifier for the machine.
    - `name` (string, required, e.g. `"machine 1"`) — The name of the machine.
  - `shift` (object, required) — The shift of the metric report.
    - `id` (integer, required, e.g. `1`) — The unique identifier of the shift.
    - `name` (string, required, e.g. `"shift 1"`) — The name of the shift.
    - `startTime` (string (date-time), required, e.g. `"2024-01-01T08:00:00.000Z"`) — The start time of the shift.
    - `endTime` (string (date-time), required, e.g. `"2024-01-01T16:00:00.000Z"`) — The end time of the shift.
    - `isActive` (boolean, required, e.g. `true`) — Whether the shift is currently active.
  - `shiftIndicators` (object, required) — Information about the shift indicator.
    - `indicatorId` (integer, optional, nullable, e.g. `1`) — The unique identifier for the indicator.
    - `annotatedDowntime` (number, optional, nullable, e.g. `0`) — Annotated downtime in minutes.
    - `availability` (number, optional, nullable, e.g. `100`) — Availability percentage.
    - `availableTime` (number, optional, nullable, e.g. `1`) — Available time in minutes.
    - `earlyStopTime` (number, optional, nullable, e.g. `0`) — Early stop time in minutes.
    - `lateStartTime` (number, optional, nullable, e.g. `0`) — Late start time in minutes.
    - `netAvailability` (number, optional, nullable, e.g. `100`) — Net availability percentage.
    - `noDataTime` (number, optional, nullable, e.g. `0`) — Time with no data in minutes.
    - `nonProgrammedDowntime` (number, optional, nullable, e.g. `0`) — Non-programmed downtime in minutes.
    - `programmedDowntime` (number, optional, nullable, e.g. `0`) — Programmed downtime in minutes.
    - `otherStopsTime` (number, optional, nullable, e.g. `0`) — Other stops time in minutes.
    - `unavailableTime` (number, optional, nullable, e.g. `0`) — Unavailable time in minutes.
  - `productionMetrics` (object, required) — Information about the production metrics.
    - `availability` (number, optional, nullable, e.g. `100`) — Availability percentage.
    - `netAvailability` (number, optional, nullable, e.g. `100`) — Net availability percentage.
    - `oee` (number, optional, nullable, e.g. `100`) — Overall Equipment Effectiveness (OEE).
    - `netOee` (number, optional, nullable, e.g. `100`) — Net OEE.
    - `quality` (number, optional, nullable, e.g. `100`) — Quality percentage.
    - `effectiveness` (number, optional, nullable, e.g. `100`) — Effectiveness percentage.
    - `minutesLostByLowQuality` (number, optional, nullable, e.g. `0`) — Minutes lost due to low quality.
    - `minutesLostByLowSpeed` (number, optional, nullable, e.g. `0`) — Minutes lost due to low speed.

#### 422 — Validation Error

Type: object (`HTTPValidationError`)

- `detail` (array of object, optional)
  - `loc` (array of string | integer, required)
  - `msg` (string, required)
  - `type` (string, required)

### Example request

```bash
curl -X POST 'https://draco.prod.pulsarml.com/v1/reports/metrics' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 1,
    "limit": 10,
    "machines": {
      "exclude": [
        1
      ],
      "include": [
        1
      ],
      "search": "machine 1"
    }
  }'
```