Skip to main content

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.