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 withprovidersofcollectMspUsage); empty while MSP billing is off.runs(array of MspRun)attempts(integer): Failures in a row; the scheduler takes a failed run again atnextAttemptAt.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 manyprogressDonecounts (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;getMspRawAnswerdownloads one.startedAt(string (date-time)): When it started.status(string): Status of the run (running,succeeded,failed). (one ofrunning,succeeded,failed)triggeredBy(string):scheduleor the person who collected.year(integer): Year of the billing month.
year(integer)
Example 200 answer:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs' \
-H "Authorization: Bearer $ACCESS_TOKEN"