Skip to main content

Bursts

A burst makes one report per audience from a template report: each variant is a copy of the template that holds its own values of what the burst varies by, such as a region or an account, so it shows only its data. A Rollstack report's burst varies by report parameters, which its datasheets read; an older report's burst, such as of a Google Slides or PowerPoint file, varies by filters of its syncs, and each variant is a copy of the file in the burst's folder.

Make a report the template of a burst with createBurst, or find one with listBursts, then see its variants, where their runs stand and who they are emailed to with listBurstVariants. Add variants by their parameter or filter values, remove them, run them all with startBurstRun, and set who each one is emailed to. Adding and running variants answer at once: follow the batch you added with getBurstVariantBatch and the variants' runs with getBurstRun, which wait for them to end. Each variant is also a report, so the /reports/{id} endpoints its type takes work on it: an older report's variants don't take the ones for Rollstack reports, such as getReportContent.

Change a burst's settings with updateBurstSettings, an older report's burst's filters with updateBurstFilters, rename it with renameBurst and delete it with deleteBurst. Its email comes two ways: each variant's own email, which its runs send to its own recipients (set them with updateBurstVariantRecipients, its settings with updateBurstVariantEmailSettings, and send now with sendBurstVariantEmails), and the burst's email configurations, each one email to its own recipients with every variant it selects (listBurstEmailConfigs and the endpoints next to it).

List bursts

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

The bursts of reports the user can see, newest first: those of Rollstack reports, whose variants differ by report parameters, and those of older reports such as Google Slides or PowerPoint files, whose variants differ by filters, as kind says. Each comes with what its variants differ by and the template report they are copied from. You can filter by name, ignoring case. Answers up to limit bursts, 50 by default and 200 at most, and a nextCursor: pass it as cursor for the next page, until it is null. listReports leaves out the reports of a burst, its template and variants.

Requires the slide_decks:read scope.

Operation ID: listBursts.

Query parameters

  • name (string): Only return bursts whose name contains this text, ignoring case: region matches Regional Review. Example: regional.
  • limit (integer): Maximum number of bursts 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 bursts on this page, most recently created first.

    • id (string, required): Unique identifier for the burst. Pass it as id to the other /bursts/{id} endpoints.
    • name (string, required): Name of the burst, as members see it in Rollstack. It is the template report's name when the burst is created, and is part of each variant report's name unless variantNaming is sameName.
    • folderId (string or null, required): The folder the burst is in, by its id in listFolders. null when the burst is at the top level.
    • owner (object, required): The member who owns the burst: whoever created it, unless ownership has since been transferred in the app.
      • 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.
    • templateReportId (string or null, required): The template report, which every variant was copied from when it was added, by its id for getReport and the other /reports/{id} endpoints. Changes to the template reach existing variants only when pushed from the app; variants added later copy it as it is then. null if the template was deleted.
    • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
    • kind (string, required): What the variants differ by. parameters: report parameters of a Rollstack report, listed in parameters and set with parameters in addBurstVariants. filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed in filters and set with filters in addBurstVariants. One of parameters, filters.
    • reportType (string, required): The type of report the burst copies, as type in listReports: SlideDeck for a Rollstack report, which bursts by parameters, any other type for an older report, which bursts by filters. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.
    • parameters (array of object, required): The template report's parameters the variants differ by, in the order their values name a variant. Each variant holds its own value of each, which its datasheets' filters read. 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 template's value of the parameter, which a variant keeps when it doesn't set one. null when the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter's value in listBursts, or of a variant's in listBurstVariants:

        • A list of values: { "type": "categorical", "values": ["EMEA"] }, with at least one value. operator can also be is_not, contains or doesnt_contain; it is is when left out.
        • A number: { "type": "number", "value": 10 }. Text: { "type": "text", "value": "EMEA" }.
        • A date range: { "type": "date", "subtype": "date_range", "startDate": "2026-01-01", "endDate": "2026-03-31" }. One date: { "type": "date", "subtype": "date_single", "date": "2026-03-31" }.
        • A month or a quarter: { "type": "date", "subtype": "date_month_year", "month": 3, "year": 2026 } (months 1 to 12), { "type": "date", "subtype": "date_quarter_year", "quarter": 1, "year": 2026 }.
        • A relative period: { "type": "date", "subtype": "date_relative", "rangeType": "lastN", "rangeN": 3, "periodType": "months" }. rangeType is current, lastN or nextN; periodType is days, weeks, months, quarters or years, or completeDays through completeYears for whole periods only.
        • 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 filters of the template report's syncs that the variants differ by, primary ones first in the order their values name a variant. Each variant holds its own value of each, applied to the syncs that read the filter's dashboard. 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.
      • primary (boolean, required): Whether the filter names the variants: a variant added without a name is named after its primary filters' values, in order. A secondary filter only narrows what each variant shows.
      • valueType (string or null, required): The kind of value the filter takes, and so the type of a variant's value of it. null when Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One of categorical, date, number, text.
    • variantCount (number, required): How many variants the burst has, including any you can't open.
    • appUrl (string (uri), required): Link that opens the burst in Rollstack.
    • createdAt (string (date-time), required): When the burst was created. listBursts returns the newest first.
    • updatedAt (string (date-time), required): When the burst's details last changed.
  • nextCursor (string or null, required): Pass it as cursor to get the next page of bursts. null when there are no more.

Create burst

POST https://api.rollstack.com/public/v1/bursts

Makes a report the template of a new burst, and answers the burst, named after the report and with no variants yet. Add them with addBurstVariants. A Rollstack report's variants differ by the report parameters in parameterIds, found with getReportParameters. An older report's variants differ by the filters in filters, found with listReportSyncFilters: a folder is made for the burst in Google Drive or OneDrive and the report's file is copied into it as the template, which can take a minute. Only the report's editors may.

Requires the slide_decks:write scope.

Operation ID: createBurst.

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

  • templateReportId (string, required): The report to make the template of the burst, by its id from listReports. You must be able to edit it, and it can't already be part of a burst. A Rollstack report must have datasheets, and becomes the template as it is. An older report must have syncs: its file is copied into a new folder for the burst, and the copy becomes the template. Example: 6c1f9a2e-3b4d-4e8f-9a1b-2c3d4e5f6a7b.
  • parameterIds (array of string (uuid)): For a Rollstack report: the template report's parameters the variants differ by, by their id from getReportParameters, in the order their values name a variant. Each must be burstable there. At least one.
  • filters (object): For an older report, such as a Google Slides or PowerPoint file: the filters of its syncs the variants differ by.
    • primaryIds (array of string, required): The filters that name the variants, by their id from listReportSyncFilters, in the order their values name a variant. 1 to 3. With more than one, each variant's file goes in a folder per value, one level per filter.
    • secondaryIds (array of string): Filters a variant can also set, which don't name it, by their id from listReportSyncFilters. Defaults to [].
  • parentFolderId (string): For an older report: the Google Drive or OneDrive folder to create the burst's folder in, by its id in that drive. The template and the variants' files go in the burst's folder. Defaults to the top of your drive.
  • driveId (string): For an older report: the shared drive parentFolderId is in. Leave it out for a folder in your own drive.
  • variantNaming (string): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. Defaults to suffix. One of sameName, prefix, suffix.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the burst. Pass it as id to the other /bursts/{id} endpoints.
  • name (string, required): Name of the burst, as members see it in Rollstack. It is the template report's name when the burst is created, and is part of each variant report's name unless variantNaming is sameName.
  • folderId (string or null, required): The folder the burst is in, by its id in listFolders. null when the burst is at the top level.
  • owner (object, required): The member who owns the burst: whoever created it, unless ownership has since been transferred in the app.
    • 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.
  • templateReportId (string or null, required): The template report, which every variant was copied from when it was added, by its id for getReport and the other /reports/{id} endpoints. Changes to the template reach existing variants only when pushed from the app; variants added later copy it as it is then. null if the template was deleted.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • kind (string, required): What the variants differ by. parameters: report parameters of a Rollstack report, listed in parameters and set with parameters in addBurstVariants. filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed in filters and set with filters in addBurstVariants. One of parameters, filters.
  • reportType (string, required): The type of report the burst copies, as type in listReports: SlideDeck for a Rollstack report, which bursts by parameters, any other type for an older report, which bursts by filters. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.
  • parameters (array of object, required): The template report's parameters the variants differ by, in the order their values name a variant. Each variant holds its own value of each, which its datasheets' filters read. 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 template's value of the parameter, which a variant keeps when it doesn't set one. null when the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter's value in listBursts, or of a variant's in listBurstVariants:

      • A list of values: { "type": "categorical", "values": ["EMEA"] }, with at least one value. operator can also be is_not, contains or doesnt_contain; it is is when left out.
      • A number: { "type": "number", "value": 10 }. Text: { "type": "text", "value": "EMEA" }.
      • A date range: { "type": "date", "subtype": "date_range", "startDate": "2026-01-01", "endDate": "2026-03-31" }. One date: { "type": "date", "subtype": "date_single", "date": "2026-03-31" }.
      • A month or a quarter: { "type": "date", "subtype": "date_month_year", "month": 3, "year": 2026 } (months 1 to 12), { "type": "date", "subtype": "date_quarter_year", "quarter": 1, "year": 2026 }.
      • A relative period: { "type": "date", "subtype": "date_relative", "rangeType": "lastN", "rangeN": 3, "periodType": "months" }. rangeType is current, lastN or nextN; periodType is days, weeks, months, quarters or years, or completeDays through completeYears for whole periods only.
      • 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 filters of the template report's syncs that the variants differ by, primary ones first in the order their values name a variant. Each variant holds its own value of each, applied to the syncs that read the filter's dashboard. 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.
    • primary (boolean, required): Whether the filter names the variants: a variant added without a name is named after its primary filters' values, in order. A secondary filter only narrows what each variant shows.
    • valueType (string or null, required): The kind of value the filter takes, and so the type of a variant's value of it. null when Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One of categorical, date, number, text.
  • variantCount (number, required): How many variants the burst has, including any you can't open.
  • appUrl (string (uri), required): Link that opens the burst in Rollstack.
  • createdAt (string (date-time), required): When the burst was created. listBursts returns the newest first.
  • updatedAt (string (date-time), required): When the burst's details last changed.

List burst email configurations

GET https://api.rollstack.com/public/v1/bursts/{id}/email-configs

A burst's email configurations, as the app's Burst email settings show them: each one email to its own recipients that includes every variant it selects, sent only when you send it. Unlike each variant's own email, which its runs send to its own recipients. What both sent is in listEmails with burstId.

Requires the slide_decks:read scope.

Operation ID: listBurstEmailConfigs.

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

Response 200

Success

application/json: array of object

  • id (string, required): Identifies the configuration. Pass it as configId to the other /email-configs/{configId} endpoints.
  • name (string or null, required): The configuration's name, as shown in the burst's Emailing tab in the app.
  • to (array of string, required): The addresses the email goes to.
  • cc (array of string, required): The addresses copied on the email, which every recipient can see.
  • bcc (array of string, required): The addresses that also receive the email without the others seeing them.
  • replyTo (array of string, required): Where replies to the email go.
  • variantIds (array of string, required): The variants the email includes, by their id in listBurstVariants. Empty includes every variant, also those added later.
  • sharingFormat (string, required): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean, required): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink.
  • zipAttachments (boolean, required): Whether the variants' files come in one zip file, with a file format.
  • emailAnalyticsEnabled (boolean, required): Whether opens of the email are tracked.
  • smtpServerId (string or null, required): The SMTP connection the email is sent through, from listSmtpConnections; null sends from Rollstack's own address.
  • createdAt (string (date-time), required): When the configuration was created.
  • updatedAt (string (date-time), required): When the configuration last changed.

Create burst email configuration

POST https://api.rollstack.com/public/v1/bursts/{id}/email-configs

Adds an email configuration to a burst and answers it: one email to its recipients with the variants it selects, every variant by default. Sends nothing. Only the burst's owner and admins may.

Requires the slide_decks:email scope.

Operation ID: createBurstEmailConfig.

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

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

  • name (string or null): The configuration's name, as shown in the burst's Emailing tab in the app.
  • to (array of string): The addresses the email goes to.
  • cc (array of string): The addresses copied on the email, which every recipient can see.
  • bcc (array of string): The addresses that also receive the email without the others seeing them.
  • replyTo (array of string): Where replies to the email go.
  • variantIds (array of string): The variants the email includes, by their id in listBurstVariants. Empty includes every variant, also those added later.
  • sharingFormat (string): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink.
  • zipAttachments (boolean): Whether the variants' files come in one zip file, with a file format.
  • emailAnalyticsEnabled (boolean): Whether opens of the email are tracked.
  • smtpServerId (string or null): The SMTP connection the email is sent through, from listSmtpConnections; null sends from Rollstack's own address.

Response 201

Success

application/json

  • id (string, required): Identifies the configuration. Pass it as configId to the other /email-configs/{configId} endpoints.
  • name (string or null, required): The configuration's name, as shown in the burst's Emailing tab in the app.
  • to (array of string, required): The addresses the email goes to.
  • cc (array of string, required): The addresses copied on the email, which every recipient can see.
  • bcc (array of string, required): The addresses that also receive the email without the others seeing them.
  • replyTo (array of string, required): Where replies to the email go.
  • variantIds (array of string, required): The variants the email includes, by their id in listBurstVariants. Empty includes every variant, also those added later.
  • sharingFormat (string, required): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean, required): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink.
  • zipAttachments (boolean, required): Whether the variants' files come in one zip file, with a file format.
  • emailAnalyticsEnabled (boolean, required): Whether opens of the email are tracked.
  • smtpServerId (string or null, required): The SMTP connection the email is sent through, from listSmtpConnections; null sends from Rollstack's own address.
  • createdAt (string (date-time), required): When the configuration was created.
  • updatedAt (string (date-time), required): When the configuration last changed.

Get burst run

GET https://api.rollstack.com/public/v1/bursts/{id}/runs

Where the runs of a burst's variants stand, such as those startBurstRun started, with how each variant's latest run ended. Waits up to waitSeconds for none of them to be running and answers as soon as that happens, so call it again while the status is running. A run started in the app or by a schedule counts too.

Requires the slide_decks:read scope.

Operation ID: getBurstRun.

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

  • 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

  • status (string, required): Where the burst's run stands. running: some variants are still running; call getBurstRun again to keep waiting. completed: none is running, and each variant's lastRunStatus says how its latest run ended. One of running, completed.
  • variants (array of object, required): The burst's variants you can see, oldest first.
    • id (string, required): The variant's report id.
    • name (string, required): The variant's report name.
    • runId (string or null, required): The variant's run in progress, whoever started it. Pass it with the variant's id to getReportRun or cancelReportRun. null once the variant isn't running.
    • lastRunStatus (string or null, required): How the variant's latest run that ended went: completed, failed or cancelled, as lastRunStatus on the report says. null if it has never run. Check lastSyncedAt to tell whether that run is the one you started; listReportRuns says why a run failed. One of running, completed, failed, cancelled, timed_out.
    • lastSyncedAt (string (date-time) or null, required): When the variant's latest run ended, whatever its outcome. null if it has never run.

Run burst variants

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

Starts a run of every variant of a burst, or of the variants passed, as startReportRun does for each: it refreshes the variant's data, and repairs a Rollstack report's slides with AI. An older report's variants run together as the app's Update runs them, in batches and behind the organization's other burst runs, so a variant can wait its turn before its run shows. Each such run updates the variant's file when it has one, and emails the variant to its recipients when its email trigger is all, as startReportRun does. The template report isn't run; run it with startReportRun. Answers each variant's run at once: follow them all with getBurstRun until none is running, or one with getReportRun, passing the variant's id and runId. A variant already running answers that run and starts nothing. From an AI client, a run that emails variants 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: startBurstRun.

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

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

  • variantIds (array of string): The variants to run, by their id in listBurstVariants, instead of every variant, such as those whose last run failed. Each must be a variant of this burst. 1 to 500 ids.

Response 202

Success

application/json

  • runs (array of object, required): The variants running, each as a run of its own report.
    • id (string, required): The variant's report id.
    • name (string, required): The variant's report name.
    • runId (string, required): The variant's run. Follow the burst's runs together with getBurstRun, or this one with the variant's id on getReportRun; cancel it with cancelReportRun.
    • started (boolean, required): Whether this request started the run. false when a run of the variant was already going, whoever started it; runId is then that run's.
  • failed (array of object, required): The variants whose run could not start, such as those you can't run since you only contribute to the burst. The others still started.
    • id (string, required): The variant's report id.
    • name (string, required): The variant's report name.
    • code (string, required): Why its run could not start, as an error code, such as forbidden.
    • message (string, required): Why its run could not start, in words.

Get burst settings

GET https://api.rollstack.com/public/v1/bursts/{id}/settings

A burst's settings, as its Settings tab in the app shows them: how its variants are named, and for an older report's burst, how each variant's run updates its file, what it does with empty charts, how it archives and how its filters match. Its folders and schedules are set in the app.

Requires the slide_decks:read scope.

Operation ID: getBurstSettings.

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

Response 200

Success

application/json

  • kind (string, required): What the burst's variants differ by, as kind in listBursts. One of parameters, filters.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • updateMethod (string, required): How each variant's run changes its file. update updates the same file with the latest data. archive first saves a copy of the file, named with the date of its previous run, then updates the original. updateVisualizations is the method email reports are created with. It applies to new variants and to the existing ones. For an older report's burst only: a Rollstack report's burst returns 400. One of update, archive, updateVisualizations.
  • variantEmptyVisualizations (string, required): What a variant's run does with a chart or table that has no data for its values. show places it empty, hideNoCascade leaves it out of the file, hideCascade hides its slide when every visualization on the slide is empty, and hideCascadeIfAtLeastOneVisualizationIsEmpty hides its slide when any of them is. For an older report's burst only: a Rollstack report's burst returns 400. One of show, hideNoCascade, hideCascade, hideCascadeIfAtLeastOneVisualizationIsEmpty.
  • archiveVariantsInFolder (boolean, required): With updateMethod archive: whether each variant's archived copies go in an archive folder next to its file, rather than beside it. For an older report's burst only: a Rollstack report's burst returns 400.
  • datestampSuffix (string, required): With updateMethod archive: the date format added to the name of each archived copy. For an older report's burst only: a Rollstack report's burst returns 400.
  • caseInsensitiveFilters (boolean, required): Whether a variant's filter values match the dashboard's values whatever their case. It applies when filters are next applied, such as with reapplyBurstFilters. For an older report's burst only: a Rollstack report's burst returns 400.

Update burst settings

PATCH https://api.rollstack.com/public/v1/bursts/{id}/settings

Changes the settings passed and answers them all. A Rollstack report's burst takes only variantNaming. An older report's run settings, such as updateMethod, also apply to its existing variants. Only the burst's owner and admins may.

Requires the slide_decks:write scope.

Operation ID: updateBurstSettings.

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

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

  • variantNaming (string): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • updateMethod (string): How each variant's run changes its file. update updates the same file with the latest data. archive first saves a copy of the file, named with the date of its previous run, then updates the original. updateVisualizations is the method email reports are created with. It applies to new variants and to the existing ones. For an older report's burst only: a Rollstack report's burst returns 400. One of update, archive, updateVisualizations.
  • variantEmptyVisualizations (string): What a variant's run does with a chart or table that has no data for its values. show places it empty, hideNoCascade leaves it out of the file, hideCascade hides its slide when every visualization on the slide is empty, and hideCascadeIfAtLeastOneVisualizationIsEmpty hides its slide when any of them is. For an older report's burst only: a Rollstack report's burst returns 400. One of show, hideNoCascade, hideCascade, hideCascadeIfAtLeastOneVisualizationIsEmpty.
  • archiveVariantsInFolder (boolean): With updateMethod archive: whether each variant's archived copies go in an archive folder next to its file, rather than beside it. For an older report's burst only: a Rollstack report's burst returns 400.
  • datestampSuffix (string): With updateMethod archive: the date format added to the name of each archived copy. For an older report's burst only: a Rollstack report's burst returns 400.
  • caseInsensitiveFilters (boolean): Whether a variant's filter values match the dashboard's values whatever their case. It applies when filters are next applied, such as with reapplyBurstFilters. For an older report's burst only: a Rollstack report's burst returns 400.

Response 200

Success

application/json

  • kind (string, required): What the burst's variants differ by, as kind in listBursts. One of parameters, filters.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • updateMethod (string, required): How each variant's run changes its file. update updates the same file with the latest data. archive first saves a copy of the file, named with the date of its previous run, then updates the original. updateVisualizations is the method email reports are created with. It applies to new variants and to the existing ones. For an older report's burst only: a Rollstack report's burst returns 400. One of update, archive, updateVisualizations.
  • variantEmptyVisualizations (string, required): What a variant's run does with a chart or table that has no data for its values. show places it empty, hideNoCascade leaves it out of the file, hideCascade hides its slide when every visualization on the slide is empty, and hideCascadeIfAtLeastOneVisualizationIsEmpty hides its slide when any of them is. For an older report's burst only: a Rollstack report's burst returns 400. One of show, hideNoCascade, hideCascade, hideCascadeIfAtLeastOneVisualizationIsEmpty.
  • archiveVariantsInFolder (boolean, required): With updateMethod archive: whether each variant's archived copies go in an archive folder next to its file, rather than beside it. For an older report's burst only: a Rollstack report's burst returns 400.
  • datestampSuffix (string, required): With updateMethod archive: the date format added to the name of each archived copy. For an older report's burst only: a Rollstack report's burst returns 400.
  • caseInsensitiveFilters (boolean, required): Whether a variant's filter values match the dashboard's values whatever their case. It applies when filters are next applied, such as with reapplyBurstFilters. For an older report's burst only: a Rollstack report's burst returns 400.

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, and see its datasheets, runs, schedules and email setup. comment also lets you add, reply to and resolve comments on its slides. edit also lets you change it: rename or move it, chat with the slides agent about it, add datasheets and read their data, 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.

Add burst variants

POST https://api.rollstack.com/public/v1/bursts/{id}/variants

Adds variants to a burst by their values of its report parameters, or of its filters for an older report's burst: each is a copy of the template report with its own values, then runs once to fetch its data. An older report's variant is a copy of its file in the burst's folder. Report parameter values and filter ids are checked first, so a request with one the burst can't take adds nothing. Answers at once with the batch's batchId and the names the variants are added with: follow the batch with getBurstVariantBatch until it ends.

Requires the slide_decks:write scope.

Operation ID: addBurstVariants.

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

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

  • variants (array of object, required): The variants to add, 1 to 500. Variants may hold the same values as one another or as an existing variant: each is added as its own report.
    • name (string): The variant's name, which its report's name is built from as the burst's variantNaming says. If omitted, it is named after the values it sets, like EMEA - Q1 2026: its parameters' values, or its primary filters' values.
    • parameters (object): For a burst by parameters: the value the variant sets of each report parameter, by its id in the burst's parameters. A parameter left out keeps the template's value. A value must be one the template's datasheet filters can take, or the request returns 400 and adds nothing. Example: {"5e7a9c1b-3d5f-4b7d-9e1a-3c5e7a9b1d3f":{"type":"categorical","values":["EMEA"]}}.
    • filters (object): For a burst by filters: the value the variant applies to each filter, by its id in the burst's filters, at least one. A filter left out keeps its value on the dashboard. An id that isn't one of the burst's filters returns 400 and adds nothing. Example: {"3b1f8c2e-6a4d-4f1e-9b2a-7c5d8e1f2a3b":{"type":"categorical","values":["EMEA"]}}.

Response 202

Success

application/json

  • batchId (string, required): Identifies the batch of variants being added. Pass it to getBurstVariantBatch, which waits for them to be added. Variants you add while another of your batches on the burst is going join it, under the same id.
  • variants (array of object, required): The variants being added, in the order sent.
    • name (string, required): The name the variant is added with.

Get burst variant batch

GET https://api.rollstack.com/public/v1/bursts/{id}/variants/batches/{batchId}

A batch of variants being added to a burst, with where each variant stands: copied from the template report, then run once to fetch its data. Waits up to waitSeconds for the batch to end and answers as soon as it does, so call it again while the status is running. Your later batch on the burst reuses the id, so this describes the latest one.

Requires the slide_decks:read scope.

Operation ID: getBurstVariantBatch.

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/.
  • batchId (string, required): The batch, by the batchId that addBurstVariants returned. A member's batches on a burst share one id, so it always refers to their latest.

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

  • batchId (string, required): Identifies the batch, as returned by addBurstVariants.
  • status (string, required): Where the batch stands. It stays running until every variant in it is added and has run once, then says how it ended.

    • running: variants are still being added. Call getBurstVariantBatch again to keep waiting.
    • completed: the batch finished. Each of variants says how it went; find the added ones among the burst's variants in listBurstVariants.
    • failed: every variant failed, or the batch stopped on an error. A variant fails both when it can't be added and when it is added but its first run fails, so some may still be among the burst's variants in listBurstVariants.
    • cancelled: the batch was stopped in the app before it finished.

    One of running, completed, failed, cancelled.

  • startedAt (string (date-time), required): When the batch started.
  • finishedAt (string (date-time) or null, required): When the batch ended, whatever its outcome. null while it is running.
  • variants (array of object, required): The variants in the batch, in the order they were sent, each with where adding it stands.
    • 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.

List sync filters

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

The filters of the dashboard an older report's sync reads, which a burst of the report can vary by: pass their ids in filters to createBurst. Read from the dashboard with your access to its connection, so it can take a few seconds. Find the report's syncs with listReportSyncs. A Rollstack report bursts by report parameters instead: see getReportParameters.

Requires the slide_decks:read scope.

Operation ID: listReportSyncFilters.

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/.
  • syncId (string, required): The sync whose dashboard filters to list, by its id from listReportSyncs.

Response 200

Success

application/json

  • filters (array of object, required): The filters of the sync's dashboard a burst can vary by, by name.
    • id (string, required): The filter's id. Pass it in filters to createBurst to make a burst whose variants differ by it.
    • name (string, required): The filter's name on the sync's dashboard.
    • valueType (string or null, required): The kind of value Rollstack can set in the filter: the type of each variant's value of it. null when Rollstack doesn't know the filter's editor. One of categorical, date, number, text.
  • unsupported (array of object, required): The dashboard's filters Rollstack can't set, so a burst can't vary by them.
    • name (string, required): The filter's name on the dashboard.

Send burst email configuration

POST https://api.rollstack.com/public/v1/bursts/{id}/email-configs/{configId}/send

Sends a burst's email configuration now: one email to its recipients with each variant it selects. Building it outlasts the request, so it goes out after the answer. Send a test with sendBurstEmailConfigTest first to check how it looks. Only the burst's owner and admins may. Sends have a low rate limit. From an AI client, the send only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:email scope.

Operation ID: sendBurstEmailConfig.

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/.
  • configId (string, required): The email configuration, by its id from listBurstEmailConfigs.

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 202

Success

application/json

  • id (string, required): The email configuration.
  • name (string or null, required): The email configuration's name.

Send variant emails

POST https://api.rollstack.com/public/v1/bursts/{id}/variants/emails

Sends each variant's own email now, to its own recipients, as the app's Send does: every variant, or those passed. The template sends nothing. Every recipient gets an email. Only the burst's owner and admins may. Sends have a low rate limit. From an AI client, the send only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:email scope.

Operation ID: sendBurstVariantEmails.

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

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

  • variantIds (array of string): The variants to act on, by their id in listBurstVariants, instead of every variant. Each must be a variant of this burst. 1 to 500 ids.

Response 202

Success

application/json

  • sending (array of object, required): The variants whose email is going out now, each to its own recipients. See each one's sends with listReportEmails.
    • id (string, required): The report's id.
    • name (string, required): The report's name.
  • skipped (array of object, required): The variants left out since their email has no one in to. Set them with updateBurstVariantRecipients.
    • id (string, required): The report's id.
    • name (string, required): The report's name.

Rename burst

PATCH https://api.rollstack.com/public/v1/bursts/{id}

Renames a burst and answers it, and with renameVariants its reports too. Only the burst's owner and admins may.

Requires the slide_decks:write scope.

Operation ID: renameBurst.

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

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

  • name (string, required): The burst's new name.
  • renameVariants (boolean): Whether to rename every report in the burst after the new name too, as variantNaming builds each name, the template included. A Rollstack report's burst renames the template, which is the report the burst was made from. Defaults to false.
  • renameFiles (boolean): For a burst of Google Slides, Google Docs, PowerPoint or Word reports: whether to also rename the burst's folders, and with renameVariants each report's file, in Google Drive or OneDrive. It goes on after the answer. Defaults to false.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the burst. Pass it as id to the other /bursts/{id} endpoints.
  • name (string, required): Name of the burst, as members see it in Rollstack. It is the template report's name when the burst is created, and is part of each variant report's name unless variantNaming is sameName.
  • folderId (string or null, required): The folder the burst is in, by its id in listFolders. null when the burst is at the top level.
  • owner (object, required): The member who owns the burst: whoever created it, unless ownership has since been transferred in the app.
    • 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.
  • templateReportId (string or null, required): The template report, which every variant was copied from when it was added, by its id for getReport and the other /reports/{id} endpoints. Changes to the template reach existing variants only when pushed from the app; variants added later copy it as it is then. null if the template was deleted.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • kind (string, required): What the variants differ by. parameters: report parameters of a Rollstack report, listed in parameters and set with parameters in addBurstVariants. filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed in filters and set with filters in addBurstVariants. One of parameters, filters.
  • reportType (string, required): The type of report the burst copies, as type in listReports: SlideDeck for a Rollstack report, which bursts by parameters, any other type for an older report, which bursts by filters. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.
  • parameters (array of object, required): The template report's parameters the variants differ by, in the order their values name a variant. Each variant holds its own value of each, which its datasheets' filters read. 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 template's value of the parameter, which a variant keeps when it doesn't set one. null when the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter's value in listBursts, or of a variant's in listBurstVariants:

      • A list of values: { "type": "categorical", "values": ["EMEA"] }, with at least one value. operator can also be is_not, contains or doesnt_contain; it is is when left out.
      • A number: { "type": "number", "value": 10 }. Text: { "type": "text", "value": "EMEA" }.
      • A date range: { "type": "date", "subtype": "date_range", "startDate": "2026-01-01", "endDate": "2026-03-31" }. One date: { "type": "date", "subtype": "date_single", "date": "2026-03-31" }.
      • A month or a quarter: { "type": "date", "subtype": "date_month_year", "month": 3, "year": 2026 } (months 1 to 12), { "type": "date", "subtype": "date_quarter_year", "quarter": 1, "year": 2026 }.
      • A relative period: { "type": "date", "subtype": "date_relative", "rangeType": "lastN", "rangeN": 3, "periodType": "months" }. rangeType is current, lastN or nextN; periodType is days, weeks, months, quarters or years, or completeDays through completeYears for whole periods only.
      • 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 filters of the template report's syncs that the variants differ by, primary ones first in the order their values name a variant. Each variant holds its own value of each, applied to the syncs that read the filter's dashboard. 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.
    • primary (boolean, required): Whether the filter names the variants: a variant added without a name is named after its primary filters' values, in order. A secondary filter only narrows what each variant shows.
    • valueType (string or null, required): The kind of value the filter takes, and so the type of a variant's value of it. null when Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One of categorical, date, number, text.
  • variantCount (number, required): How many variants the burst has, including any you can't open.
  • appUrl (string (uri), required): Link that opens the burst in Rollstack.
  • createdAt (string (date-time), required): When the burst was created. listBursts returns the newest first.
  • updatedAt (string (date-time), required): When the burst's details last changed.

Delete burst

DELETE https://api.rollstack.com/public/v1/bursts/{id}

Deletes a burst with every report in it, the template included, as the app does, and can't be undone. A Rollstack report's burst uses the report it was made from as its template, so that report is deleted too. Files in Google Drive or OneDrive stay. Only the burst's owner may. From an AI client, the deletion only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:write scope.

Operation ID: deleteBurst.

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

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 200

Success

application/json

  • id (string, required): The deleted burst.
  • name (string, required): The deleted burst's name.

Set variant email settings

PATCH https://api.rollstack.com/public/v1/bursts/{id}/variants/email-settings

Changes how the variants' own emails are sent, as the app's Burst settings in its Emailing tab do: only the settings passed, on the template, whose settings new variants copy, and on the variants. Each keeps its recipients: set them with updateBurstVariantRecipients. Sends no email. Members who only contribute change their own variants. See a report's settings with getReportEmailConfig.

Requires the slide_decks:email scope.

Operation ID: updateBurstVariantEmailSettings.

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

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

  • variantIds (array of string): The reports to change, by their id: variants from listBurstVariants, and the burst's templateReportId, whose settings new variants copy. If omitted, the template and every variant you can edit.
  • smtpServerId (string or null): The SMTP connection to send the emails through, from listSmtpConnections; null sends from Rollstack's own address. If omitted, each report keeps its own sender.
  • sharingFormat (string): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. If omitted, stays as it is. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink. If omitted, stays as it is.
  • trigger (string): Which of the report's runs email it automatically. A run emails it when it updates everything, or when all its failures are in ignoredFailureStatusMessages. On a slide deck, all and scheduled work the same way: only runs started by its schedules (see getReportSchedules) send the email, and a slide deck with no datasheets is never emailed by its runs. On an older report, all emails after every run of the whole report, whether started by a schedule, with startReportRun or in the app, and scheduled only after runs its schedules start; a run of only some syncs never emails it. With none (Manual in the app), no run sends it: the email goes out only when sent with sendReportEmail or from the app. If omitted, stays as it is. One of all, none, scheduled.
  • groupRecipients (boolean): Whether each variant sends one email to all its to addresses together, rather than one email per address. If omitted, stays as it is.
  • ignoredFailureStatusMessages (array of string): The failures that shouldn't stop a run from emailing a variant (see trigger), such as the error.code values from listReportSyncs. If omitted, stays as it is.

    The other values describe why a sync of an older report failed, and have an effect only on older reports:

    • dashboard_not_found, or the older tableau_view_not_found: the dashboard, Tableau workbook, Power BI report or spreadsheet could not be found.
    • dashboard_tab_not_found: the dashboard tab, Tableau view, Power BI report page or spreadsheet sheet could not be found.
    • dashboard_not_ready: the dashboard took too long to load.
    • dashboard_has_errors: the dashboard or spreadsheet failed to load because of an error in the tool it comes from.
    • dashboard_invalid_layout: the dashboard's layout is invalid, and it needs to be saved again.
    • element_not_found, or the older metabase_element_not_found and looker_element_not_found: the visualization could not be found.
    • slide_not_found, or the older google_slide_not_found: the slide that shows the visualization could not be found.
    • file_not_found: the spreadsheet file the visualization comes from could not be found.
    • sheet_not_found: the spreadsheet sheet could not be found.
    • sheet_hidden: the spreadsheet sheet is hidden and needs to be unhidden.
    • range_not_found: the spreadsheet range could not be found.
    • duplicate_file_failed: Rollstack could not prepare the spreadsheet file for the update.
    • merged_range_on_filter_range: the visualization has merged cells, which filters can't be applied to.
    • insufficient_permissions: the owner doesn't have edit access to the file.
    • image_cropping_failed: Rollstack could not crop the visualization's image.
    • visualization_not_found: the visualization could not be found in the dashboard.
    • visualization_not_ready: the visualization took too long to load.
    • visualization_has_errors: the visualization failed to load because of an error in the tool it comes from.
    • visualization_empty, or the older empty_data: the visualization is empty.
    • invalid_credentials: the connection's credentials are invalid.
    • missing_credentials: the connection's credentials were deleted, or the owner's access to it was suspended.
    • instance_unavailable: the data source's instance is temporarily unavailable.
    • column_not_found: a column the native chart uses is missing from its data.
    • fetch_summary_data_error, fetch_visual_specification_error, missing_data, missing_formatted_value and viz_not_ready: Rollstack could not fetch the data of a native chart.
    • incorrect_data_structure: the native chart's structure doesn't fit its data.
    • malformed_data: Rollstack could not fetch the data of a native chart or, from Snowflake, Databricks or BigQuery, the query is invalid.
    • worksheet_not_found: the Tableau worksheet could not be found.
    • sync_not_found: the visualization was deleted.
    • file_update_failed: the data was fetched but could not be written into the file.
  • emailAnalyticsEnabled (boolean): Whether to track when recipients open the emails. true returns 403 unless email analytics is on for the organization. If omitted, stays as it is.

Response 200

Success

application/json

  • updated (array of object, required): The reports whose email settings changed. Their recipients stay as they were.
    • id (string, required): The report's id.
    • name (string, required): The report's name.

Update burst email configuration

PATCH https://api.rollstack.com/public/v1/bursts/{id}/email-configs/{configId}

Changes the fields passed of a burst's email configuration and answers it. Sends nothing. Only the burst's owner and admins may.

Requires the slide_decks:email scope.

Operation ID: updateBurstEmailConfig.

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/.
  • configId (string, required): The email configuration, by its id from listBurstEmailConfigs.

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

  • name (string or null): The configuration's name, as shown in the burst's Emailing tab in the app.
  • to (array of string): The addresses the email goes to.
  • cc (array of string): The addresses copied on the email, which every recipient can see.
  • bcc (array of string): The addresses that also receive the email without the others seeing them.
  • replyTo (array of string): Where replies to the email go.
  • variantIds (array of string): The variants the email includes, by their id in listBurstVariants. Empty includes every variant, also those added later.
  • sharingFormat (string): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink.
  • zipAttachments (boolean): Whether the variants' files come in one zip file, with a file format.
  • emailAnalyticsEnabled (boolean): Whether opens of the email are tracked.
  • smtpServerId (string or null): The SMTP connection the email is sent through, from listSmtpConnections; null sends from Rollstack's own address.

Response 200

Success

application/json

  • id (string, required): Identifies the configuration. Pass it as configId to the other /email-configs/{configId} endpoints.
  • name (string or null, required): The configuration's name, as shown in the burst's Emailing tab in the app.
  • to (array of string, required): The addresses the email goes to.
  • cc (array of string, required): The addresses copied on the email, which every recipient can see.
  • bcc (array of string, required): The addresses that also receive the email without the others seeing them.
  • replyTo (array of string, required): Where replies to the email go.
  • variantIds (array of string, required): The variants the email includes, by their id in listBurstVariants. Empty includes every variant, also those added later.
  • sharingFormat (string, required): How the email delivers the report. pdf and ppt send it as a PDF or PowerPoint file, attached or behind a download button (see sendAttachmentAsLink); a slide deck leaves its hidden slides out. link sends a link to the Google Drive or OneDrive file an older report updates, shared with the recipients as set in the app; an email report sends its content in the email itself, and a slide deck has no such file, so one whose settings still contain link is emailed as a PDF behind a download button. cloudLink (Exported link in the app), for slide decks only, sends a link to the copy exported to Google Drive or OneDrive and shares it with the addresses in to, cc and bcc with the sharing permission set in the app, viewer unless changed there; if no permission is set, as after PDF or PPT was picked in the app, the copy isn't shared with them. One of link, pdf, ppt, cloudLink.
  • sendAttachmentAsLink (boolean, required): Whether the email puts the pdf or ppt file behind a Download PDF or Download PPT button instead of attaching it. When false, the file is attached. Has no effect with cloudLink.
  • zipAttachments (boolean, required): Whether the variants' files come in one zip file, with a file format.
  • emailAnalyticsEnabled (boolean, required): Whether opens of the email are tracked.
  • smtpServerId (string or null, required): The SMTP connection the email is sent through, from listSmtpConnections; null sends from Rollstack's own address.
  • createdAt (string (date-time), required): When the configuration was created.
  • updatedAt (string (date-time), required): When the configuration last changed.

Delete burst email configuration

DELETE https://api.rollstack.com/public/v1/bursts/{id}/email-configs/{configId}

Deletes a burst's email configuration. Its past sends stay. Only the burst's owner and admins may.

Requires the slide_decks:email scope.

Operation ID: deleteBurstEmailConfig.

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/.
  • configId (string, required): The email configuration, by its id from listBurstEmailConfigs.

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 200

Success

application/json

  • id (string, required): The email configuration.
  • name (string or null, required): The email configuration's name.

Set variant recipients

PUT https://api.rollstack.com/public/v1/bursts/{id}/variants/recipients

Sets who each variant's email goes to, replacing its to, cc and bcc. Its other email settings, such as its sender and which runs send it, stay as copied from the template; a variant without email settings gets the defaults. Sends no email. As in the app, the burst's owner and admins can set any variant's recipients, other members only those of variants they own or can edit; the others are skipped, as is a variant with several recipient groups, which the app asks to reconcile first.

Requires the slide_decks:email scope.

Operation ID: updateBurstVariantRecipients.

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

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

  • variants (array of object, required): The variants whose recipients to replace, 1 to 500. The other variants, and the rest of each variant's email settings, stay as they are.
    • id (string, required): The variant, by its id in listBurstVariants.
    • to (array of string, required): The addresses to send the variant's email to. If empty, no one receives it. At most 100 addresses across to, cc and bcc.
    • cc (array of string): The addresses to copy on the variant's email, which every recipient can see. If omitted, no one is copied. Defaults to [].
    • bcc (array of string): The addresses to also send the variant's email to without the other recipients seeing them. If omitted, no one is blind-copied. Defaults to [].

Response 200

Success

application/json

  • updated (array of string, required): The variants whose recipients were replaced, by their id.
  • skipped (array of string, required): The variants passed that were left as they were, by their id: those you can't edit, since you only contribute to the burst, and ids that aren't variants of it.

Update burst filters

PUT https://api.rollstack.com/public/v1/bursts/{id}/filters

Replaces the filters an older report's burst varies by, then writes every variant's values into its syncs again, which can take a minute, and answers the burst. A filter left out is removed with every variant's value of it, unless replace carries those values to its new filter: confirm with the user first. Variants keep their files and names. Only the burst's owner and admins may. A Rollstack report's burst varies by report parameters and returns 400.

Requires the slide_decks:write scope.

Operation ID: updateBurstFilters.

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

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

  • primaryIds (array of string, required): The filters that name the variants, by their id in the burst's filters or from listReportSyncFilters, in the order their values name a variant. 1 to 3.
  • secondaryIds (array of string): Filters a variant can also set, which don't name it. Defaults to [].
  • replace (array of object): Carries every variant's value of a filter you're replacing to its new filter, such as one moved to another dashboard. Without it, a filter left out is removed together with every variant's value of it, which can't be undone. Defaults to [].
    • fromId (string, required): A filter the burst varies by now, by its id in its filters.
    • toId (string, required): The new filter, among primaryIds or secondaryIds, that takes its values.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the burst. Pass it as id to the other /bursts/{id} endpoints.
  • name (string, required): Name of the burst, as members see it in Rollstack. It is the template report's name when the burst is created, and is part of each variant report's name unless variantNaming is sameName.
  • folderId (string or null, required): The folder the burst is in, by its id in listFolders. null when the burst is at the top level.
  • owner (object, required): The member who owns the burst: whoever created it, unless ownership has since been transferred in the app.
    • 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.
  • templateReportId (string or null, required): The template report, which every variant was copied from when it was added, by its id for getReport and the other /reports/{id} endpoints. Changes to the template reach existing variants only when pushed from the app; variants added later copy it as it is then. null if the template was deleted.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • kind (string, required): What the variants differ by. parameters: report parameters of a Rollstack report, listed in parameters and set with parameters in addBurstVariants. filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed in filters and set with filters in addBurstVariants. One of parameters, filters.
  • reportType (string, required): The type of report the burst copies, as type in listReports: SlideDeck for a Rollstack report, which bursts by parameters, any other type for an older report, which bursts by filters. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.
  • parameters (array of object, required): The template report's parameters the variants differ by, in the order their values name a variant. Each variant holds its own value of each, which its datasheets' filters read. 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 template's value of the parameter, which a variant keeps when it doesn't set one. null when the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter's value in listBursts, or of a variant's in listBurstVariants:

      • A list of values: { "type": "categorical", "values": ["EMEA"] }, with at least one value. operator can also be is_not, contains or doesnt_contain; it is is when left out.
      • A number: { "type": "number", "value": 10 }. Text: { "type": "text", "value": "EMEA" }.
      • A date range: { "type": "date", "subtype": "date_range", "startDate": "2026-01-01", "endDate": "2026-03-31" }. One date: { "type": "date", "subtype": "date_single", "date": "2026-03-31" }.
      • A month or a quarter: { "type": "date", "subtype": "date_month_year", "month": 3, "year": 2026 } (months 1 to 12), { "type": "date", "subtype": "date_quarter_year", "quarter": 1, "year": 2026 }.
      • A relative period: { "type": "date", "subtype": "date_relative", "rangeType": "lastN", "rangeN": 3, "periodType": "months" }. rangeType is current, lastN or nextN; periodType is days, weeks, months, quarters or years, or completeDays through completeYears for whole periods only.
      • 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 filters of the template report's syncs that the variants differ by, primary ones first in the order their values name a variant. Each variant holds its own value of each, applied to the syncs that read the filter's dashboard. 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.
    • primary (boolean, required): Whether the filter names the variants: a variant added without a name is named after its primary filters' values, in order. A secondary filter only narrows what each variant shows.
    • valueType (string or null, required): The kind of value the filter takes, and so the type of a variant's value of it. null when Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One of categorical, date, number, text.
  • variantCount (number, required): How many variants the burst has, including any you can't open.
  • appUrl (string (uri), required): Link that opens the burst in Rollstack.
  • createdAt (string (date-time), required): When the burst was created. listBursts returns the newest first.
  • updatedAt (string (date-time), required): When the burst's details last changed.

Reapply burst filters

POST https://api.rollstack.com/public/v1/bursts/{id}/filters/reapply

Writes each variant's filter values into its syncs again, as the app's Reapply does: after syncs were added to the template, or a filter changed on its dashboard. It reads the dashboards with your access to their connections, and runs nothing: run the variants afterwards with startBurstRun. Members who only contribute reapply their own variants. A Rollstack report's burst returns 400.

Requires the slide_decks:write scope.

Operation ID: reapplyBurstFilters.

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

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

  • variantIds (array of string): The variants to act on, by their id in listBurstVariants, instead of every variant. Each must be a variant of this burst. 1 to 500 ids.

Response 200

Success

application/json

  • reapplied (array of object, required): The variants whose filter values were written into their syncs again. Run them with startBurstRun to see the change.
    • id (string, required): The variant's report id.
    • name (string, required): The variant's report name.

Remove burst variants

POST https://api.rollstack.com/public/v1/bursts/{id}/variants/remove

Removes variants of a burst by their ids, and deletes their reports. Find the ids with listBurstVariants, which shows each variant's parameter or filter values, and confirm them with the user. An older report's variant file stays in Google Drive or OneDrive. The user must be able to edit every variant passed, or nothing is removed: the burst's owner and admins can edit them all, other members only their own. From an AI client, the removal only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:write scope.

Operation ID: removeBurstVariants.

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

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

  • variantIds (array of string, required): The variants to remove, by their id in listBurstVariants, which shows each one's parameter or filter values. Each must be a variant of this burst. 1 to 500 ids.

Response 200

Success

application/json

  • removed (array of object, required): The variants removed, whose reports are deleted.
    • id (string, required): The removed variant's report id.
    • name (string, required): The removed variant's report name.

Send burst email configuration test

POST https://api.rollstack.com/public/v1/bursts/{id}/email-configs/{configId}/test

Sends a burst's email configuration to you alone, to check how it looks before sending it. Only the burst's owner and admins may. Sends have a low rate limit.

Requires the slide_decks:email scope.

Operation ID: sendBurstEmailConfigTest.

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/.
  • configId (string, required): The email configuration, by its id from listBurstEmailConfigs.

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 200

Success

application/json

  • id (string, required): The email configuration.
  • name (string or null, required): The email configuration's name.