Skip to main content

Get report run

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

A run's status and the datasheets, or visualizations on a report of another type than SlideDeck, it could not refresh. Waits up to waitSeconds for the run to end and answers as soon as it does, so call it again while the status is running. A user's later run of the report reuses the id, so this describes the latest one.

Requires the slide_decks:read scope.

Operation ID: getReportRun.

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/.
  • runId (string, required): The run, by the runId that startReportRun returned. Runs of a report started by the same member share one id, so it always refers to that member's latest run of the report.

Query parameters

  • waitSeconds (integer): How long this call waits for the work to finish, in seconds: the message to the slides agent on getReportMessage, the run on getReportRun, the batch of variants being added on getBurstVariantBatch, the runs of a burst's variants on getBurstRun. It returns as soon as the work is done, or as things stand once the time is up, so call it again while status is still queued or running. 0 returns at once. Defaults to 20; at most 30. Defaults to 20.

Response 200

Success

application/json

  • runId (string, required): Identifies the run, as returned by startReportRun.
  • status (string, required): Where the run stands. It stays running until the run ends, then says how it ended.

    • running: the run is still updating the report. Call getReportRun again to keep waiting.
    • completed: the run finished. Datasheets, or visualizations on a report of another type than SlideDeck, it could not refresh, if any, keep their previous data and are listed in errors.
    • failed: nothing could be refreshed, or the run stopped on an error. errors lists the datasheets or visualizations it could not refresh.
    • cancelled: the run was stopped before it finished, for example with cancelReportRun or "Cancel update" in the app. Datasheets and visualizations it had already refreshed keep their new data.
    • timed_out: the run went past its time limit and was stopped.

    One of running, completed, failed, cancelled, timed_out.

  • startedAt (string (date-time), required): When the run started.
  • finishedAt (string (date-time) or null, required): When the run ended, whatever its outcome. null while it is running.
  • errors (array of object, required): The datasheets, or visualizations on a report of another type than SlideDeck, the run could not refresh, each with the reason. While the run is running, those that have failed so far; on a SlideDeck report, once the run has failed, also those it had not finished. Empty when nothing failed. To run only these datasheets again, pass their ids as datasheetIds to startReportRun.
    • datasheetId (string or null, required): The datasheet that could not be refreshed, as id in listReportDatasheets. null on a report of another type than SlideDeck, whose runs refresh visualizations instead: name then names the visualization.
    • name (string, required): The datasheet's or visualization's name, as shown in the app. The report's own name when a run of a report of another type than SlideDeck failed as a whole, with no visualization to blame.
    • message (string, required): Why it could not be refreshed, for example an error reading its source or computing its data. Empty when no reason was recorded.