Skip to main content

Runs

Update a report from its sources. A run reads every datasheet again, or only the ones you pass, recalculates the report's numbers, and repairs with AI the calculations and slides the new data broke. Schedules start the same run.

On a report whose type isn't SlideDeck, a run refreshes every visualization instead, as Update in the app does. It updates the report's file, such as a Google Slides presentation; an Email report has no file. Recipients get the report by email when its email trigger is all. Its errors then name the visualizations it could not refresh.

Start a run, then follow it with getReportRun until it ends. A report runs once at a time: starting a run while one is going answers that run instead. To run up to 50 whole reports in one call, use batchStartReportRuns.

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.
  • nextCursor (string or null, required): Pass it as cursor to get the next page of runs. null when there are no more.

Start report run

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

Refreshes a report's data, or only some of its datasheets, then repairs failed calculations and the slides with AI. On a report of another type than SlideDeck, such as a Google Slides presentation, refreshes every sync, or only the syncIds given, instead, as Update in the app does, updating its file when it has one (an Email report has none). A run of the whole report then emails it when its email trigger is all; a run of only some syncIds never does. Answers the run's id at once; while a run of the report is already going, from the API, the app or its schedule, it answers that run's id with started false and starts nothing. Pass repairSlides false to leave the slides as they are, when you wrote them yourself and will check and fix them. From an AI client, a run that emails the report 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: startReportRun.

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/.

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

application/json

  • datasheetIds (array of string (uuid)): The datasheets to update, from listReportDatasheets, instead of the whole report. Each must be a datasheet of this report. Unlike a run of the whole report, which reads every source again, a run of only some datasheets reuses the data last read from their sources: it reads a source again only if that data is missing or expired, or what the datasheet reads has changed, such as its source, its filters or the connection it reads with, as when you replace an uploaded file with replaceDataset. If omitted, the run updates the whole report. 1 to 500 ids. Only on reports whose type is SlideDeck: a report of another type has syncs instead, so passing it returns 400.
  • syncIds (array of string (uuid)): The syncs to update, from listReportSyncs, instead of the whole report, such as the ones whose status is failed. Each must be a sync of this report. A paused sync is skipped, as in the app. A run of only some syncs never emails the report. If omitted, the run updates the whole report. 1 to 500 ids. Only on reports other than SlideDeck, which has datasheets instead, so passing it on a slide deck returns 400.
  • 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

  • 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.

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.

List report syncs

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

The syncs of a report other than a SlideDeck, such as a Google Slides presentation or an email report: each chart, table or text it pulls from a source, with how it did the last time it updated and why it failed. Pass the failed ones' ids as syncIds to startReportRun to update only those. A SlideDeck report has datasheets instead and returns 400.

Requires the slide_decks:read scope.

Operation ID: listReportSyncs.

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/.

Response 200

Success

application/json: array of object

  • id (string, required): Unique identifier for the sync. Pass it in syncIds to startReportRun to update only some syncs, or to updateReportSchedules for a schedule that updates only some.
  • name (string, required): The sync's name, as shown in the report's Syncs tab in Rollstack.
  • sourceType (string, required): Where the sync gets its data, such as Tableau, Looker or GoogleSheets. One of GoogleSheet, GoogleExcel, MicrosoftExcel, Tableau, Salesforce, Metabase, PowerBI, Looker, RollstackVariable, Lightdash, Omni, Sigma, Snowflake, Databricks, BigQuery, CsvUpload, XlsxUpload, ManualTable, Dbt.
  • status (string, required): How the sync did the last time it updated: succeeded, partiallySucceeded or failed. draft for a sync that hasn't updated yet, active while it updates, and inactive when a check before the run stopped it, such as a source the owner can no longer reach. One of active, draft, succeeded, partiallySucceeded, failed, inactive.
  • error (object or null, required): Why the last update failed or was stopped. null when the sync succeeded or never updated.
    • code (string or null, required): Why the sync failed, such as dashboard_not_found. One of tableau_view_not_found, dashboard_not_found, dashboard_tab_not_found, dashboard_not_ready, dashboard_has_errors, dashboard_invalid_layout, metabase_element_not_found, looker_element_not_found, element_not_found, google_slide_not_found, slide_not_found, file_not_found, sheet_not_found, sheet_hidden, range_not_found, duplicate_file_failed, merged_range_on_filter_range, insufficient_permissions, image_cropping_failed, visualization_not_found, visualization_not_ready, visualization_has_errors, visualization_empty, invalid_credentials, missing_credentials, instance_unavailable, column_not_found, empty_data, fetch_summary_data_error, fetch_visual_specification_error, incorrect_data_structure, missing_data, missing_formatted_value, malformed_data, viz_not_ready, worksheet_not_found, sync_not_found, file_update_failed, internal_server_error.
    • details (string or null, required): More about the failure, as the app shows it.
  • slideIndex (number or null, required): Where the sync is in the file, as the 0-based index of its slide or page. null when it has no fixed place, such as an email report.
  • paused (boolean, required): Whether the sync is turned off, so runs skip it until it is turned on again in the app.
  • lastSuccessfulUpdateAt (string (date-time) or null, required): When the sync last updated successfully. null if it never has.

List runs of all reports

GET https://api.rollstack.com/public/v1/runs

The runs that ended of every report the user can see, of any type, newest first, each with its report, for questions such as what failed overnight: pass status failed and since. Same fields as listReportRuns. 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: listRuns.

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.
  • status (string): Only the runs that ended this way, such as failed, as status in the runs. If omitted, every run. One of succeeded, partiallySucceeded, failed, cancelled, inactive, skipped.
  • since (string (date-time)): Only what happened at or after this time, as an ISO 8601 date and time in UTC, such as 2026-11-08T18:00:00Z. If omitted, from the start. Example: 2026-11-08T18:00:00Z.

Response 200

Success

application/json

  • data (array of object, required): The runs that ended of every report you can see, of any type, newest first, whoever started them. To find what failed overnight, pass status failed and since. A run still going isn't listed until it ends.

    • 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.
    • report (object, required): The report the run updated.
      • id (string, required): The report's id, to pass to the /reports/{id} endpoints, such as getReport.
      • name (string or null, required): The report's name.
  • nextCursor (string or null, required): Pass it as cursor to get the next page of runs. null when there are no more.

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.

Cancel report run

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

Cancels a run of a report, whoever started it. Only its editors may. A run that already ended stays as it is.

Requires the slide_decks:run scope.

Operation ID: cancelReportRun.

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.

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.

Response 204

Success, no content