Skip to main content

List report runs

GET https://api.rollstack.com/public/v1/reports/{id}/runs

The runs of a report of any type that ended, newest first, with how each ended, what started it and why it failed, for questions such as why last night's update failed. Answers up to limit runs, 20 by default and 200 at most, and a nextCursor: pass it as cursor for the next page, until it is null.

Requires the slide_decks:read scope.

Operation ID: listReportRuns.

Path parameters

  • id (string, required): The report to act on, of any type, by its id from listReports or createReport. You can also copy it from the report's link in Rollstack (appUrl): it's the part right after /slides/ or /destinations/.

Query parameters

  • limit (integer): Maximum number of runs to return on this page, from 1 to 200. Defaults to 20.
  • cursor (string): Where to continue the list: pass the nextCursor returned with the previous page to get the next one. Omit it for the first page. Example: 6c1f9a2e-3b4d-4e8f-9a1b-2c3d4e5f6a7b.

Response 200

Success

application/json

  • data (array of object, required): The report's runs that ended, newest first, whoever started them: in the app, through the API or on a schedule. A run still going isn't listed until it ends: running in getReport says whether one is, and getReportRun follows the one startReportRun started.

    • id (string, required): Identifies the run in the history.
    • status (string, required): How the run ended.

      • succeeded: it refreshed everything.
      • partiallySucceeded: it refreshed some of the report and failed the rest, which kept its previous data.
      • failed: nothing could be refreshed, or the run stopped on an error. error says why.
      • cancelled: it was stopped before it finished.
      • skipped: it had nothing to refresh, such as a report with no datasheets, or a variant no longer valid for its burst.
      • inactive: nothing it could refresh was active.

      One of succeeded, partiallySucceeded, failed, cancelled, inactive, skipped.

    • trigger (string, required): scheduled when one of the report's schedules started it; manual when someone started it, in the app, with startReportRun, or by approving an update the slides agent proposed. One of manual, scheduled.
    • startedBy (object or null, required): The member whose run it was. null if their account was deleted.
      • id (number, required): The member's user id, the same as their id in listMembers.
      • name (string, required): The member's name, as shown in Rollstack.
      • email (string, required): The member's email address.
    • startedAt (string (date-time), required): When the run started.
    • finishedAt (string (date-time), required): When the run ended.
    • error (string or null, required): Why the run failed or stopped, as shown in the app. null when the run recorded no error.
    • failedVisualizations (array of object, required): On a report whose type isn't SlideDeck, up to 20 visualizations the run could not refresh, with the reason; they kept their previous data. Always empty on a SlideDeck report, whose runs don't record their datasheets: listReportDatasheets gives each datasheet's error from its latest update.
      • name (string, required)
      • message (string, required)
    • updatedSlidesCount (number or null, required): How many slides the run changed. null when the run did not count them.
    • visualizationsCount (number, required): How many visualizations the run updated, on a report whose type isn't SlideDeck. getRun lists them.
    • insightsCount (number, required): How many insights the run wrote. getRun lists them.
    • updateMethod (string, required): How the run updated the report's file, as the report's update method was when it ran. One of update, archive, updateVisualizations.
    • burst (object or null, required): The burst the report is a variant of. null for a report that isn't one.
      • id (string, required): The burst's id, to pass to the /bursts/{id} endpoints.
      • name (string or null, required): The burst's name.
    • variantFilters (array of object, required): On a burst's variant, the filter values it holds, as the Update runs page shows them. Empty otherwise.
      • name (string, required): The filter's name.
      • value (string, required): The variant's value of it, as the app shows it.
  • nextCursor (string or null, required): Pass it as cursor to get the next page of runs. null when there are no more.