Skip to main content

Update report parameter

PATCH https://api.rollstack.com/public/v1/reports/{id}/parameters/{parameterId}

Changes a parameter of a report, such as its value to show the report for another region, as the app's report parameters editor does: what you send changes and the rest stays. A new value is written into the filters and columns it links and their datasheets are read again, so the report's slides change; follow that read with runId. Answers the parameter. Only the report's editors may.

Requires the slide_decks:write scope.

Operation ID: updateReportParameter.

Path parameters

  • id (string, required): The report to act on, by its id from listReports or createReport. Only reports whose type is SlideDeck work here: another type, such as a Google Slides presentation, returns 400. You can also copy it from the report's link in Rollstack: it's the part right after /slides/.
  • parameterId (string (uuid), required): The parameter to act on, by its id in parameters from getReportParameters.

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): The parameter's new name, as shown in Rollstack. It can't be the name of another parameter of the report. Example: Region.
  • filterIds (array of string (uuid)): All the filters the parameter links from now on, by their id in filters from getReportParameters, replacing the ones it links: a filter left out keeps the value it holds, and a filter added must have no other parameterId. If omitted, it links the same filters.
  • columns (array of object): All the columns the parameter links from now on, by datasheetId and column as columns in getReportParameters lists them, replacing the ones it links: a column left out keeps the row filter it holds, and a column added must have no other parameterId. If omitted, it links the same columns.
    • datasheetId (string (uuid), required): The datasheet's id, as datasheetId in columns from getReportParameters.
    • column (string, required): The column's name, as column in columns from getReportParameters.
  • value (object or null): The parameter's new value, of the valueType of the filters it links. It is written into those filters and their datasheets are read again with it, so the report's slides change. null clears it, and the filters keep the values they hold. If omitted, the value stays. 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)

Response 200

Success

application/json

  • id (string, required): The report parameter's id. Pass it in parameterIds to createBurst when burstable is true.
  • name (string, required): The report parameter's name, as shown in Rollstack.
  • value (object or null, required): The parameter's value, which the report's datasheets read through the filters it links. null when it has none, and those filters keep their own values. 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)
  • columns (array of object, required): The columns of datasheets the parameter links: its value is written into each as a row filter, in that datasheet only. Empty when it links none.
    • datasheetId (string, required): The datasheet's id, as in listReportDatasheets.
    • datasheetName (string or null, required): The datasheet's name, or null if it has none.
    • column (string, required): The column's name in the datasheet's source.
    • kind (string, required): The kind of value that filters the column, and so the type of a parameter value that reaches it: categorical takes a list, number a number and date a date. One of categorical, number, date.
    • isLinked (boolean, required): false once the column was unlinked in Rollstack: the parameter no longer writes into it.
  • burstable (boolean, required): Whether a burst can vary by the parameter: it links at least one filter whose valueType isn't null, or at least one column that is still linked. A parameter that links neither can't be.
  • runId (string or null, required): The run that reads again the datasheets the value was written into, as runId in getReportRun. When a run of the report is already going, it reads them after that run. null when no value was written, or when you can't run the report.