List burst variants
- 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
GET https://api.rollstack.com/public/v1/bursts/{id}/variants
A burst's variants the user can open, oldest first, each with its values of the burst's parameters or filters, how its latest run went, whether one is going, and who its email goes to. adding lists the variants the user is still adding. Answers up to limit variants, 50 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: listBurstVariants.
Path parameters
id(string, required): The burst to act on, by itsidfromlistBursts. You can also copy it from the burst's link in Rollstack: it's the part right after/collections/.
Query parameters
limit(integer): Maximum number of variants to return on this page, from 1 to 200. Defaults to50.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 variants on this page that you can open, oldest first. Each variant is a report of the burst'sreportType: pass itsidtogetReport,startReportRunand the other/reports/{id}endpoints its type takes.runningandlastRunStatustell where its runs stand.id(string, required): Unique identifier for the report. Pass it asidto the other/reports/{id}endpoints.type(string, required): The kind of report, which decides the endpoints that work on it.SlideDeck: a slide deck built in Rollstack. Every/reports/{id}endpoint works on it, exceptlistReportSyncsandconvertReport.GoogleSlides,GoogleDocs,MicrosoftPowerPoint,MicrosoftWord: a file in Google Drive or OneDrive that Rollstack updates with its visualizations.UploadedPPTXFile: a PowerPoint file uploaded to Rollstack, which it updates the same way.Email: an email report, whose visualizations Rollstack sends in an email.
On a report that isn't a
SlideDeck, onlygetReport,updateReport,deleteReport,shareReport,unshareReport,getReportSchedules,updateReportSchedules,startReportRun,listReportRuns,getReportRun,cancelReportRun,listReportSyncsand the email endpoints (getReportEmailConfig,updateReportEmailConfig,listReportEmails,sendReportEmail,sendReportTestEmail) work, andconvertReporton aGoogleSlidesorMicrosoftPowerPointreport. The other/reports/{id}endpoints takeSlideDeckreports only, as theiridsays, and return400.One of
GoogleDocs,GoogleSlides,MicrosoftPowerPoint,MicrosoftWord,Email,UploadedPPTXFile,SlideDeck.name(string, required): Name of the report, as members see it in Rollstack. Change it withupdateReport.folderId(string or null, required): The folder the report is in, by itsidinlistFolders.nullwhen the report is at the top level, outside any folder.owner(object, required): The member who owns the report: whoever created it, unless ownership has since been transferred, in the app or withtransferReportOwnership. Only the owner can delete the report.id(number, required): The owner's user id, the same as theiridinlistMembers.name(string, required): The owner's name, as shown in Rollstack.email(string, required): The owner's email address. Rollstack emails this address when a scheduled run of the report fails, whilenotifyOnFailureistrue.
permission(string or null, required): Your access to the report, as the user the API key belongs to.viewlets you open and export it: on aSlideDeck, read its slides withgetReportContentandgetReportSlideImages; on any other report, also see its runs, schedules and email setup.commentalso lets you read, add, reply to and resolve comments on aSlideDeck's slides.editalso lets you change it: rename or move it, chat with the slides agent about it, read its slide HTML, datasheets and their data, report parameters, history, runs, schedules and email setup, start runs, set its schedules and email, send its email, and share it. It's nevernullhere, since the API only returns reports you can at least view. One ofview,comment,edit.timezone(string or null, required): The report's timezone, such asAmerica/New_York. The slides agent uses it to tell today's date, and the report's emails show the time of its last successful update ({{last_updated_at}}) in it. On a report that updates a file, such as a Google Slides presentation, it's also the timezone of the file's date variables, unless the organization'stimezonereplaces it. Schedules don't use it: each has its owntimezone.nullwhen the report has none, in which case the slides agent uses UTC. Reports created withcreateReportstart with the organization'stimezonefromgetOrganization, if it has one.notifyOnFailure(boolean, required): Whether Rollstack emails the report's owner when a scheduled run fails or some of its datasheets, or a file's visualizations, fail to refresh, copying everyone innotificationMailingList. Runs started in the app or withstartReportRunnever send this email. New reports start withtrue.lastSyncedAt(string (date-time) or null, required): When the report's latest run ended, whatever its outcome.nullif the report has never run.lastSuccessfulUpdateAt(string (date-time) or null, required): When the report's latest fully successful run ended: one that refreshed every datasheet it ran on, or every visualization on a report that updates a file, with none failing. Runs with nothing to refresh don't count. The report's emails show this time as{{last_updated_at}}.nulluntil the report has had such a run.lastRunStatus(string or null, required): How the report's latest run ended.completed: it finished, even if some datasheets or visualizations failed to refresh or it had none to refresh; on aSlideDeckreport,listReportDatasheetsshows each datasheet'serror.failed: it stopped on an error, or none of its datasheets or visualizations could be refreshed.cancelled: it was stopped before it finished, for example withcancelReportRun.nullif the report has never run.runningandtimed_outnever appear here: checkrunningto see whether a run is in progress. One ofrunning,completed,failed,cancelled,timed_out.running(boolean, required): Whether a run of the report is in progress, whoever started it, such as you withstartReportRun, a member in the app, or one of its schedules. While it'strue,startReportRunreturns that run instead of starting another.appUrl(string (uri), required): Link that opens the report in Rollstack.fileUrl(string or null, required): Link that opens the Google Slides, Google Docs, PowerPoint or Word file the report updates.nullfor a slide deck, an email report or an uploaded PowerPoint file, which have no file to open, and for a Microsoft file whose link Rollstack has not read yet.createdAt(string (date-time), required): When the report was created.listReportsreturns the newest first.updatedAt(string (date-time), required): When the report's details last changed, such as its name, folder or owner, or the outcome of its latest run.parameters(array of object, required): The variant's value of each parameter the burst varies by, in the burst's order. Empty for a burst byfilters.id(string, required): The report parameter's id on the template report. Use it as a key ofparametersinaddBurstVariants.name(string, required): The report parameter's name, as shown in Rollstack.value(object or null, required): The value the variant holds: the one it was added with, or the template's when it set none.nullwhen neither had one.- When
typeiscategoricaltype(categorical, required)values(array of string or number, required)operator(string): One ofis,is_not,contains,doesnt_contain.
- When
typeisdateandsubtypeisdate_rangetype(date, required)subtype(date_range, required)startDate(string, required)endDate(string, required)
- When
typeisdateandsubtypeisdate_relativetype(date, required)subtype(date_relative, required)rangeType(string, required): One ofcurrent,lastN,nextN.rangeN(number, required)periodType(string, required): One ofdays,weeks,months,quarters,years,completeDays,completeWeeks,completeMonths,completeQuarters,completeYears.
- When
typeisdateandsubtypeisdate_month_yeartype(date, required)subtype(date_month_year, required)month(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_quarter_yeartype(date, required)subtype(date_quarter_year, required)quarter(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_singletype(date, required)subtype(date_single, required)date(string, required)
- When
typeisdateandsubtypeisdate_nulltype(date, required)subtype(date_null, required)
- When
typeisnumbertype(number, required)value(number, required)
- When
typeistexttype(text, required)value(string, required)
- When
filters(array of object, required): The variant's value of each filter the burst varies by, in the burst's order. Empty for a burst byparameters.id(string, required): The filter's id. Use it as a key offiltersinaddBurstVariants.name(string, required): The filter's name on its dashboard, as shown in Rollstack.value(object or null, required): The value the variant applies to the filter, as it was added with.nullwhen it sets none, and the filter keeps its value on the dashboard.- When
typeiscategoricaltype(categorical, required)values(array of string or number, required)operator(string): One ofis,is_not,contains,doesnt_contain.
- When
typeisdateandsubtypeisdate_rangetype(date, required)subtype(date_range, required)startDate(string, required)endDate(string, required)
- When
typeisdateandsubtypeisdate_relativetype(date, required)subtype(date_relative, required)rangeType(string, required): One ofcurrent,lastN,nextN.rangeN(number, required)periodType(string, required): One ofdays,weeks,months,quarters,years,completeDays,completeWeeks,completeMonths,completeQuarters,completeYears.
- When
typeisdateandsubtypeisdate_month_yeartype(date, required)subtype(date_month_year, required)month(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_quarter_yeartype(date, required)subtype(date_quarter_year, required)quarter(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_singletype(date, required)subtype(date_single, required)date(string, required)
- When
typeisdateandsubtypeisdate_nulltype(date, required)subtype(date_null, required)
- When
typeisnumbertype(number, required)value(number, required)
- When
typeistexttype(text, required)value(string, required)
- When
recipients(object, required): Who the variant's email goes to, all empty until its own email is set up, as on a variant whose burst emails only through the configurationslistBurstEmailConfigslists. Set them withupdateBurstVariantRecipients.to(array of string, required): The addresses the report's email is sent to. When empty, no one receives it: the report's runs send no email andsendReportEmailreturns 400.cc(array of string, required): The addresses copied on the report's email, which every recipient can see.bcc(array of string, required): The addresses that also receive the report's email without the other recipients seeing them.
nextCursor(string or null, required): Pass it ascursorto get the next page of variants.nullwhen there are no more.adding(array of object, required): The variants you are adding withaddBurstVariantsor in the app, while that is still going. Empty once every one is done. To wait for variants you added, follow thebatchIdfromaddBurstVariantswithgetBurstVariantBatchrather than listing again.name(string, required): The name the variant is added with, asaddBurstVariantsreturned it.status(string, required): Where adding it stands.queued: it waits for the variants before it.running: its report is being copied from the template and run for the first time.completed: it is among the burst's variants inlistBurstVariants, though its first run may have only partly completed, as itslastRunStatussays.failed: either it could not be added, or its report was added but its first run failed. Look for it inlistBurstVariantsto tell which.cancelled: it was cancelled in the app, before it was added or during its first run. Its report may still be among the burst's variants. One ofqueued,running,completed,failed,cancelled.error(string or null, required): Why the variant failed, when that is known, whilestatusisfailed.nullotherwise, including when its report was added and only its first run failed.