Skip to main content

List burst variants

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 its id from listBursts. 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 to 50.
  • 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 variants on this page that you can open, oldest first. Each variant is a report of the burst's reportType: pass its id to getReport, startReportRun and the other /reports/{id} endpoints its type takes. running and lastRunStatus tell where its runs stand.

    • id (string, required): Unique identifier for the report. Pass it as id to 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, except listReportSyncs and convertReport.
      • 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, only getReport, updateReport, deleteReport, shareReport, unshareReport, getReportSchedules, updateReportSchedules, startReportRun, listReportRuns, getReportRun, cancelReportRun, listReportSyncs and the email endpoints (getReportEmailConfig, updateReportEmailConfig, listReportEmails, sendReportEmail, sendReportTestEmail) work, and convertReport on a GoogleSlides or MicrosoftPowerPoint report. The other /reports/{id} endpoints take SlideDeck reports only, as their id says, and return 400.

      One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.

    • name (string, required): Name of the report, as members see it in Rollstack. Change it with updateReport.
    • folderId (string or null, required): The folder the report is in, by its id in listFolders. null when 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 with transferReportOwnership. Only the owner can delete the report.
      • id (number, required): The owner's user id, the same as their id in listMembers.
      • 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, while notifyOnFailure is true.
    • permission (string or null, required): Your access to the report, as the user the API key belongs to. view lets you open and export it: on a SlideDeck, read its slides with getReportContent and getReportSlideImages; on any other report, also see its runs, schedules and email setup. comment also lets you read, add, reply to and resolve comments on a SlideDeck's slides. edit also 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 never null here, since the API only returns reports you can at least view. One of view, comment, edit.
    • timezone (string or null, required): The report's timezone, such as America/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's timezone replaces it. Schedules don't use it: each has its own timezone. null when the report has none, in which case the slides agent uses UTC. Reports created with createReport start with the organization's timezone from getOrganization, 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 in notificationMailingList. Runs started in the app or with startReportRun never send this email. New reports start with true.
    • lastSyncedAt (string (date-time) or null, required): When the report's latest run ended, whatever its outcome. null if 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}}. null until 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 a SlideDeck report, listReportDatasheets shows each datasheet's error. 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 with cancelReportRun. null if the report has never run. running and timed_out never appear here: check running to see whether a run is in progress. One of running, completed, failed, cancelled, timed_out.
    • running (boolean, required): Whether a run of the report is in progress, whoever started it, such as you with startReportRun, a member in the app, or one of its schedules. While it's true, startReportRun returns 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. null for 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. listReports returns 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 by filters.
      • id (string, required): The report parameter's id on the template report. Use it as a key of parameters in addBurstVariants.
      • 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. null when neither had one.
        • When type is categorical
          • type (categorical, required)
          • values (array of string or number, required)
          • operator (string): One of is, is_not, contains, doesnt_contain.
        • When type is date and subtype is date_range
          • type (date, required)
          • subtype (date_range, required)
          • startDate (string, required)
          • endDate (string, required)
        • When type is date and subtype is date_relative
          • type (date, required)
          • subtype (date_relative, required)
          • rangeType (string, required): One of current, lastN, nextN.
          • rangeN (number, required)
          • periodType (string, required): One of days, weeks, months, quarters, years, completeDays, completeWeeks, completeMonths, completeQuarters, completeYears.
        • When type is date and subtype is date_month_year
          • type (date, required)
          • subtype (date_month_year, required)
          • month (number, required)
          • year (number, required)
        • When type is date and subtype is date_quarter_year
          • type (date, required)
          • subtype (date_quarter_year, required)
          • quarter (number, required)
          • year (number, required)
        • When type is date and subtype is date_single
          • type (date, required)
          • subtype (date_single, required)
          • date (string, required)
        • When type is date and subtype is date_null
          • type (date, required)
          • subtype (date_null, required)
        • When type is number
          • type (number, required)
          • value (number, required)
        • When type is text
          • type (text, required)
          • value (string, required)
    • 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 by parameters.
      • id (string, required): The filter's id. Use it as a key of filters in addBurstVariants.
      • 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. null when it sets none, and the filter keeps its value on the dashboard.
        • When type is categorical
          • type (categorical, required)
          • values (array of string or number, required)
          • operator (string): One of is, is_not, contains, doesnt_contain.
        • When type is date and subtype is date_range
          • type (date, required)
          • subtype (date_range, required)
          • startDate (string, required)
          • endDate (string, required)
        • When type is date and subtype is date_relative
          • type (date, required)
          • subtype (date_relative, required)
          • rangeType (string, required): One of current, lastN, nextN.
          • rangeN (number, required)
          • periodType (string, required): One of days, weeks, months, quarters, years, completeDays, completeWeeks, completeMonths, completeQuarters, completeYears.
        • When type is date and subtype is date_month_year
          • type (date, required)
          • subtype (date_month_year, required)
          • month (number, required)
          • year (number, required)
        • When type is date and subtype is date_quarter_year
          • type (date, required)
          • subtype (date_quarter_year, required)
          • quarter (number, required)
          • year (number, required)
        • When type is date and subtype is date_single
          • type (date, required)
          • subtype (date_single, required)
          • date (string, required)
        • When type is date and subtype is date_null
          • type (date, required)
          • subtype (date_null, required)
        • When type is number
          • type (number, required)
          • value (number, required)
        • When type is text
          • type (text, required)
          • value (string, required)
    • 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 configurations listBurstEmailConfigs lists. Set them with updateBurstVariantRecipients.
      • 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 and sendReportEmail returns 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 as cursor to get the next page of variants. null when there are no more.
  • adding (array of object, required): The variants you are adding with addBurstVariants or in the app, while that is still going. Empty once every one is done. To wait for variants you added, follow the batchId from addBurstVariants with getBurstVariantBatch rather than listing again.
    • name (string, required): The name the variant is added with, as addBurstVariants returned 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 in listBurstVariants, though its first run may have only partly completed, as its lastRunStatus says. failed: either it could not be added, or its report was added but its first run failed. Look for it in listBurstVariants to 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 of queued, running, completed, failed, cancelled.
    • error (string or null, required): Why the variant failed, when that is known, while status is failed. null otherwise, including when its report was added and only its first run failed.