## List the usage runs of a month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs`

Module: Trade · operationId: `listMspRuns` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

One run per provider and month with its state, item count, progress while it runs and the file names of its stored raw answers (`rawAnswers`), plus the active providers.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Runs (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `month` (integer)
- `providers` (array of string): The active providers a collection runs, in their order – also those without a run of the month yet (each can be collected alone with `providers` of `collectMspUsage`); empty while MSP billing is off.
- `runs` (array of MspRun)
  - `attempts` (integer): Failures in a row; the scheduler takes a failed run again at `nextAttemptAt`.
  - `error` (string): Why the run failed.
  - `finishedAt` (string (date-time)): When it finished; absent while running.
  - `id` (string (uuid)): Id of the run.
  - `itemCount` (integer): Number of usage items collected.
  - `month` (integer): Month (1–12) of the billing month.
  - `nextAttemptAt` (string (date-time)): When the scheduler retries a failed run; missing otherwise.
  - `progressDone` (integer): How far a running run is: Ingram subscription details read, Sophos pages read. Missing while unknown; a new claim clears it.
  - `progressTotal` (integer): Of how many `progressDone` counts (Ingram subscriptions, Sophos pages). Missing while unknown or when the provider cannot tell.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `rawAnswers` (array of string): File names of the run's raw provider answers, stored in the database; `getMspRawAnswer` downloads one.
  - `startedAt` (string (date-time)): When it started.
  - `status` (string): Status of the run (`running`, `succeeded`, `failed`). (one of `running`, `succeeded`, `failed`)
  - `triggeredBy` (string): `schedule` or the person who collected.
  - `year` (integer): Year of the billing month.
- `year` (integer)

Example 200 answer:

```json
{
  "month": 10,
  "providers": [
    "mailstore",
    "sophos",
    "ingram",
    "itc",
    "itc-backup",
    "itc-licenses"
  ],
  "runs": [
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:00:12Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f01",
      "itemCount": 9,
      "month": 10,
      "provider": "mailstore",
      "rawAnswers": [
        "instances.json"
      ],
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-02T05:01:05Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "itemCount": 41,
      "month": 10,
      "progressDone": 2,
      "progressTotal": 2,
      "provider": "sophos",
      "rawAnswers": [
        "usage-page-1.json",
        "usage-page-2.json"
      ],
      "startedAt": "2026-11-02T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:04:31Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "itemCount": 164,
      "month": 10,
      "progressDone": 160,
      "progressTotal": 160,
      "provider": "ingram",
      "rawAnswers": [
        "subscriptions-search.json",
        "subscriptions-details.json"
      ],
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-03T06:10:02Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f04",
      "itemCount": 6,
      "month": 10,
      "provider": "itc",
      "rawAnswers": [
        "vm-report-2026-10.csv"
      ],
      "startedAt": "2026-11-03T06:10:00Z",
      "status": "succeeded",
      "triggeredBy": "anna.weber@muster-it.example",
      "year": 2026
    }
  ],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
