Runs
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
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 anytype, by itsidfromlistReportsorcreateReport. 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 to20.cursor(string): Where to continue the list: pass thenextCursorreturned 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:runningingetReportsays whether one is, andgetReportRunfollows the onestartReportRunstarted.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.errorsays 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):scheduledwhen one of the report's schedules started it;manualwhen someone started it, in the app, withstartReportRun, or by approving an update the slides agent proposed. One ofmanual,scheduled.startedBy(object or null, required): The member whose run it was.nullif their account was deleted.id(number, required): The member's user id, the same as theiridinlistMembers.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.nullwhen the run recorded no error.failedVisualizations(array of object, required): On a report whosetypeisn'tSlideDeck, up to 20 visualizations the run could not refresh, with the reason; they kept their previous data. Always empty on aSlideDeckreport, whose runs don't record their datasheets:listReportDatasheetsgives each datasheet'serrorfrom its latest update.name(string, required)message(string, required)
updatedSlidesCount(number or null, required): How many slides the run changed.nullwhen the run did not count them.
nextCursor(string or null, required): Pass it ascursorto get the next page of runs.nullwhen 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 anytype, by itsidfromlistReportsorcreateReport. 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, fromlistReportDatasheets, 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 withreplaceDataset. If omitted, the run updates the whole report. 1 to 500 ids. Only on reports whosetypeisSlideDeck: a report of another type has syncs instead, so passing it returns400.syncIds(array of string (uuid)): The syncs to update, fromlistReportSyncs, instead of the whole report, such as the ones whosestatusisfailed. Each must be a sync of this report. Apausedsync 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 thanSlideDeck, which has datasheets instead, so passing it on a slide deck returns400.repairSlides(boolean): Whether Rollstack repairs the slides with AI once the data is in: failed calculations, and text the new data made wrong. Passfalseto read the data only, when you check and fix the slides yourself. If omitted, the slides are repaired. Only on reports whosetypeisSlideDeck.
Response 202
Success
application/json
runId(string, required): Identifies the run. Pass it asrunIdtogetReportRunto follow the run until it ends, or tocancelReportRunto stop it.started(boolean, required): Whether this request started a new run.falsewhen 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,datasheetIdsandsyncIdsare ignored, andrunIdis that run's id. To run the report with your request, wait for that run to end withgetReportRun, then callstartReportRunagain.
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 anytype, by itsidfromlistReportsorcreateReport. 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 therunIdthatstartReportRunreturned. 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 ongetReportMessage, the run ongetReportRun, the batch of variants being added ongetBurstVariantBatch, the runs of a burst's variants ongetBurstRun. It returns as soon as the work is done, or as things stand once the time is up, so call it again whilestatusis stillqueuedorrunning.0returns at once. Defaults to20; at most30. Defaults to20.
Response 200
Success
application/json
runId(string, required): Identifies the run, as returned bystartReportRun.status(string, required): Where the run stands. It staysrunninguntil the run ends, then says how it ended.running: the run is still updating the report. CallgetReportRunagain to keep waiting.completed: the run finished. Datasheets, or visualizations on a report of another type thanSlideDeck, it could not refresh, if any, keep their previous data and are listed inerrors.failed: nothing could be refreshed, or the run stopped on an error.errorslists the datasheets or visualizations it could not refresh.cancelled: the run was stopped before it finished, for example withcancelReportRunor "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.nullwhile it isrunning.errors(array of object, required): The datasheets, or visualizations on a report of another type thanSlideDeck, the run could not refresh, each with the reason. While the run isrunning, those that have failed so far; on aSlideDeckreport, once the run hasfailed, also those it had not finished. Empty when nothing failed. To run only these datasheets again, pass their ids asdatasheetIdstostartReportRun.datasheetId(string or null, required): The datasheet that could not be refreshed, asidinlistReportDatasheets.nullon a report of another type thanSlideDeck, whose runs refresh visualizations instead:namethen 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 thanSlideDeckfailed 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 anytype, by itsidfromlistReportsorcreateReport. 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 insyncIdstostartReportRunto update only some syncs, or toupdateReportSchedulesfor 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 asTableau,LookerorGoogleSheets. One ofGoogleSheet,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,partiallySucceededorfailed.draftfor a sync that hasn't updated yet,activewhile it updates, andinactivewhen a check before the run stopped it, such as a source the owner can no longer reach. One ofactive,draft,succeeded,partiallySucceeded,failed,inactive.error(object or null, required): Why the last update failed or was stopped.nullwhen the sync succeeded or never updated.code(string or null, required): Why the sync failed, such asdashboard_not_found. One oftableau_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.nullwhen 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.nullif 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 to20.cursor(string): Where to continue the list: pass thenextCursorreturned 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 asfailed, asstatusin the runs. If omitted, every run. One ofsucceeded,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 as2026-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, passstatusfailedandsince. 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.errorsays 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):scheduledwhen one of the report's schedules started it;manualwhen someone started it, in the app, withstartReportRun, or by approving an update the slides agent proposed. One ofmanual,scheduled.startedBy(object or null, required): The member whose run it was.nullif their account was deleted.id(number, required): The member's user id, the same as theiridinlistMembers.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.nullwhen the run recorded no error.failedVisualizations(array of object, required): On a report whosetypeisn'tSlideDeck, up to 20 visualizations the run could not refresh, with the reason; they kept their previous data. Always empty on aSlideDeckreport, whose runs don't record their datasheets:listReportDatasheetsgives each datasheet'serrorfrom its latest update.name(string, required)message(string, required)
updatedSlidesCount(number or null, required): How many slides the run changed.nullwhen the run did not count them.report(object, required): The report the run updated.id(string, required): The report'sid, to pass to the/reports/{id}endpoints, such asgetReport.name(string or null, required): The report's name.
nextCursor(string or null, required): Pass it ascursorto get the next page of runs.nullwhen 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 anytype, by theiridfromlistReports. 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. Passfalseto read the data only, when you check and fix the slides yourself. If omitted, the slides are repaired. Only on reports whosetypeisSlideDeck.
Response 202
Success
application/json
results(array of object, required): One result per report, each naming itsid.- When
statusisdoneid(string, required): The report, by itsidfromids.status(done, required): The call succeeded on this report.result(object, required): The report's run, asstartReportRunanswers it.runId(string, required): Identifies the run. Pass it asrunIdtogetReportRunto follow the run until it ends, or tocancelReportRunto stop it.started(boolean, required): Whether this request started a new run.falsewhen 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,datasheetIdsandsyncIdsare ignored, andrunIdis that run's id. To run the report with your request, wait for that run to end withgetReportRun, then callstartReportRunagain.
- When
statusisfailedid(string, required): The report, by itsidfromids.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 asapi-key-missing-scopeordata-validation-error. Use it, rather thanmessage, 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 asbody.emails.0: Invalid email address.statusCode(number, required): The HTTP status the same call on this report alone would answer, such as404or403.
- When
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 anytype, by itsidfromlistReportsorcreateReport. 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 therunIdthatstartReportRunreturned. 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