Skip to main content

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.