Skip to main content

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.