Skip to main content

Start report runs in a batch

POST https://api.rollstack.com/public/v1/reports/batch-run

Starts a run of each of up to 50 reports of any type, as startReportRun does for one: each run updates its whole report, and a run of a report of another type than SlideDeck emails it when its email trigger is all. To update only some datasheets or syncs of a report, call startReportRun. Answers one result per report, each naming its id, with its run's id at once: follow each run with getReportRun. A report already running answers that run with started false, and a report you can't run fails on its own while the others still start. From an AI client, a batch of runs that emails any of the reports only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:run scope.

Operation ID: batchStartReportRuns.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • ids (array of string, required): The reports to act on, of any type, by their id from listReports. From 1 to 50 ids; an id listed twice is acted on once.
  • repairSlides (boolean): Whether Rollstack repairs the slides with AI once the data is in: failed calculations, and text the new data made wrong. Pass false to read the data only, when you check and fix the slides yourself. If omitted, the slides are repaired. Only on reports whose type is SlideDeck.

Response 202

Success

application/json

  • results (array of object, required): One result per report, each naming its id.
    • When status is done
      • id (string, required): The report, by its id from ids.
      • status (done, required): The call succeeded on this report.
      • result (object, required): The report's run, as startReportRun answers it.
        • runId (string, required): Identifies the run. Pass it as runId to getReportRun to follow the run until it ends, or to cancelReportRun to stop it.
        • started (boolean, required): Whether this request started a new run. false when a run of the report was already in progress, whoever started it: through the API, in the app or on one of its schedules. In that case nothing new starts, datasheetIds and syncIds are ignored, and runId is that run's id. To run the report with your request, wait for that run to end with getReportRun, then call startReportRun again.
    • When status is failed
      • id (string, required): The report, by its id from ids.
      • status (failed, required): The call failed on this report and changed nothing on it. The other reports are unaffected.
      • error (object, required): Why this report failed, as the endpoint for one report would answer. Retry only these reports.
        • code (string, required): A stable, machine-readable code for the error, such as api-key-missing-scope or data-validation-error. Use it, rather than message, to handle specific errors in your code.
        • message (string, required): A human-readable explanation of what went wrong, to log or show to people. When the request's path parameters, query or body are invalid (data-validation-error), it lists each invalid field by its path, with the problem, such as body.emails.0: Invalid email address.
        • statusCode (number, required): The HTTP status the same call on this report alone would answer, such as 404 or 403.