ConnectCloud Developers

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:

{
  "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"

View as Markdown · Interactive reference · OpenAPI