# List shifts (https://docs.pulsarml.com/v1/api-reference/shifts/get-shifts)

List your shifts that overlap a time range, past or upcoming, to find the `id` that
`POST /v1/shifts/{shift_id}/operator` and `POST /v1/shifts/{shift_id}/defects` take.

A shift is returned when any part of it falls between `from` and `to`: it ends after `from` and
starts before `to`. So a night shift from 22:00 to 06:00 shows up in a range covering either
day. The range may span at most **31 days**; page through longer periods with consecutive
ranges. Shifts come back ordered by `start`, then by machine.

Narrow the list with `machineId`, repeated for several machines:

```
GET /v1/shifts?from=2026-10-12T00:00:00Z&to=2026-10-13T00:00:00Z&machineId=12
```

Shifts excluded from metrics are listed too, with `isConsidered: false`.

## `GET /v1/shifts`

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.

### Query parameters

- `from` (string (date-time), required, e.g. `"2026-10-12T00:00:00Z"`) — Return shifts that end after this moment. A time without a UTC offset is read as UTC.
- `to` (string (date-time), required, e.g. `"2026-10-13T00:00:00Z"`) — Return shifts that start before this moment, at most 31 days after `from`. A time without a UTC offset is read as UTC.
- `machineId` (array of integer, optional, nullable) — Only shifts of these machines, as returned by `GET /v1/machines`. Repeat it for several machines (`machineId=12&machineId=13`). All of your machines when omitted.

### Responses

#### 200 — The shifts that overlap the range, ordered by start

Type: array of object

- `id` (integer, required, e.g. `48213`) — The shift's id, for `POST /v1/shifts/{shift_id}/operator` and `POST /v1/shifts/{shift_id}/defects`.
- `machineId` (integer, required, e.g. `12`) — The machine the shift belongs to.
- `title` (string, required, e.g. `"Morning"`) — The shift's name.
- `start` (string (date-time), required, e.g. `"2026-10-12T06:00:00Z"`) — When the shift starts.
- `end` (string (date-time), required, e.g. `"2026-10-12T14:00:00Z"`) — When the shift ends.
- `targetQuantity` (integer, required, e.g. `1200`) — The shift's production target, in units, as set by `PUT /v1/shifts/targets`.
- `isConsidered` (boolean, required, e.g. `true`) — Whether the shift counts toward metrics. Excluded shifts are listed too, with `false`.

#### 422 — Validation Error

Type: object (`HTTPValidationError`)

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

### Example request

```bash
curl -X GET 'https://draco.prod.pulsarml.com/v1/shifts?from=2026-10-12T00%3A00%3A00Z&to=2026-10-13T00%3A00%3A00Z' \
  -H 'x-api-key: <YOUR_API_KEY>'
```