Skip to main content

Parameters

Named values of a report, such as a region, that it writes into the filters of the dashboards its datasheets read, and as row filters into columns of its datasheets. One parameter can link differently named filters on several dashboards, and columns of several datasheets, and setting its value filters all of them the same way. A burst's variants each hold their own value of the parameters it varies by.

See a report's parameters and the filters and columns they can link with getReportParameters, then create one with createReportParameter. Change a parameter's value, name, filters or columns with updateReportParameter, for example to show the report for another region, or delete it with deleteReportParameter. A report that reads no dashboard has no filters to link, but its datasheets can have columns to link once they were read.

Get report parameters

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

A report's parameters, with which ones a burst can vary by, the dashboard filters and the datasheet columns a parameter can link, with the parameter that already links each.

Requires the slide_decks:read scope.

Operation ID: getReportParameters.

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

Response 200

Success

application/json

  • parameters (array of object, required): The report's parameters, oldest first. Empty until one is created, here or in the app.

    • 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.
  • filters (array of object, required): The filters a parameter can link: those of the dashboards the report's datasheets read. Empty when the report reads no dashboard, such as one built only from uploaded files and spreadsheet ranges, which can't have parameters.
    • id (string, required): The filter's id. Pass it in filterIds to createReportParameter.
    • name (string, required): The filter's name on its dashboard.
    • connectionType (string, required): The kind of connection the dashboard is on, such as Looker. One of GoogleSheet, GoogleExcel, MicrosoftExcel, Tableau, Salesforce, Metabase, PowerBI, Looker, RollstackVariable, Lightdash, Omni, Sigma, Snowflake, Databricks, BigQuery, CsvUpload, XlsxUpload, ManualTable, Dbt.
    • dashboardName (string, required): The dashboard the filter is on, as its connection names it.
    • datasheets (array of object, required): The report's datasheets that read the filter's dashboard, which a parameter linking it writes its value into.
      • id (string, required): The datasheet's id, as in listReportDatasheets.
      • name (string, required): The datasheet's name.
    • parameterId (string or null, required): The parameter that links the filter, by its id in parameters. A filter follows one parameter at most, so a new parameter can only link filters where this is null.
    • valueType (string or null, required): The kind of value Rollstack can set in the filter, and so the type of a parameter value that reaches it. null when only the dashboard's own embed can edit the filter: a parameter can link it, but can't set its value or be burst by it. One of categorical, date, number, text.
  • columns (array of object, required): The columns a parameter can link: those of the datasheets the report has already read, from a source Rollstack can filter by rows, with a kind of value that can filter them. A datasheet never read, or read before Rollstack kept its columns' types, has none: see datasheetsToRefresh.
    • datasheetId (string, required): The datasheet's id, as in listReportDatasheets. Pass it in columns to createReportParameter.
    • datasheetName (string, required): The datasheet's name.
    • column (string, required): The column's name in the datasheet's source.
    • kind (string, required): The kind of value that filters the column: categorical takes a list, number a number and date a date. One of categorical, number, date.
    • parameterId (string or null, required): The parameter that links the column, by its id in parameters. A column follows one parameter at most, so a new parameter can only link columns where this is null.
  • datasheetsToRefresh (array of object, required): The datasheets whose columns can be linked once the report is run again, as a run reads them.
    • id (string, required)
    • name (string, required)

Create report parameter

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

Creates a parameter of a report, linked to the dashboard filters and datasheet columns given, as the app's report parameters editor does. With a value, writes it into those filters, and as a row filter into those columns, and reads their datasheets again. Answers the parameter. Only the report's editors may.

Requires the slide_decks:write scope.

Operation ID: createReportParameter.

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

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 parameter's name, as shown in Rollstack. It can't be the name of another parameter of the report. Example: Region.
  • filterIds (array of string (uuid)): The filters the parameter links, by their id in filters from getReportParameters: its value is written into each, in every datasheet that reads its dashboard. Each must have no parameterId yet. A burst can vary by the parameter only if one of them has a valueType, or it links a column. Defaults to [].
  • columns (array of object): The columns the parameter links, by datasheetId and column as columns in getReportParameters lists them: its value is written into each as a row filter, in that datasheet only. Each must have no parameterId yet. The value's type follows the first filter's valueType, or the first column's kind when it links no filter that can be set. Defaults to [].
    • 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 value, of the valueType of the filters it links. When set, it is written into those filters and their datasheets are read again with it, so the report's slides change. If null or omitted, as for a parameter a burst's variants will set, the 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.

    Defaults to null.

    • 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 201

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.

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.

Delete report parameter

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

Deletes a parameter of a report, as the app's report parameters editor does. The filters and columns it linked keep the last value it wrote, and a burst that varies by it stops varying by it. Refused for the last parameter a burst varies by, and on a burst's variant, whose parameters follow its template report's: delete it there. Only the report's editors may.

Requires the slide_decks:write scope.

Operation ID: deleteReportParameter.

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.

Response 204

Success, no content