## Get the history of a workflow instance (tenant:access)

`GET /api/workflow/v1/instances/{instanceId}/log`

Module: Workflow · operationId: `getInstanceHistory` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** History entries, oldest first (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of HistoryEntry, required): Items of the list
  - `action` (string): Free text, e.g. `Step completed`, `CLAIMED`, `UNCLAIMED`, `FORCE_PULLED`, `NOTE`, `CANCELLED`, `Rückfrage gestellt`
  - `actor` (string): E-mail of the person, or `SYSTEM`
  - `branch` (string): `regular` or `inquiry`
  - `changes` (ChangeSetDiff): What trade changed, with old values
    - `added` (array of LineSnapshot): Lines added by duplicating
    - `changeSetId` (string): Id of the applied change set (instance:revision:content hash)
    - `deleted` (array of LineSnapshot): Lines deleted, with their old values
    - `header` (array of FieldChange): Changed transaction fields
    - `lines` (array of object): Changed fields of existing lines
      - `changes` (array of FieldChange): Changed fields of the line
      - `lineId` (string): Trade line id
      - `position` (integer): Position of the line in the transaction
    - `totals` (object): Transaction totals before and after the changes
      - `new` (Totals)
      - `old` (Totals)
  - `color` (string): Color of the chosen transition button
  - `comment` (string): Comment, note text or inquiry answer
  - `group` (string): HR group UUID of the step
  - `icon` (string): Icon of the chosen transition button
  - `nextStep` (string): Name of the step the transition led to
  - `stepName` (string): Step the entry belongs to (`START`/`END` for the start and end of the workflow)
  - `timestamp` (string (date-time)): When it happened
  - `user` (string): E-mail of the person the step was assigned to
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "action": "Workflow started",
      "actor": "SYSTEM",
      "nextStep": "kontierung",
      "stepName": "START",
      "timestamp": "2026-11-17T08:41:12Z"
    },
    {
      "action": "CLAIMED",
      "actor": "christina.adler@muster-it.example",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:05:40Z"
    },
    {
      "action": "Step completed",
      "actor": "christina.adler@muster-it.example",
      "branch": "regular",
      "changes": {
        "added": [],
        "changeSetId": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60:2:4d7a0c",
        "deleted": [],
        "header": [],
        "lines": [
          {
            "changes": [
              {
                "field": "lineData.costCenter",
                "label": "Kostenstelle",
                "new": "4100",
                "old": ""
              }
            ],
            "lineId": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
            "position": 1
          }
        ],
        "totals": {
          "new": {
            "gross": 6911.52,
            "net": 5808,
            "tax": 1103.52
          },
          "old": {
            "gross": 6911.52,
            "net": 5808,
            "tax": 1103.52
          }
        }
      },
      "color": "primary",
      "comment": "Kostenstelle Vertrieb.",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "icon": "i-lucide-arrow-right",
      "nextStep": "freigabe",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:12:03Z"
    }
  ],
  "total": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/instances/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/log' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
