The formula column calculates values using mathematical expressions, text functions, and references to other columns. Formulas are computed server-side and cannot be written via the API.

Via the API, the formula column supports read and create operations.

Queries

Formula columns can be queried through the column_values field on items using an inline fragment on FormulaValue.

The computed result is returned in the display_value field. The text and value fields are not populated for formula columns.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on FormulaValue {
        id
        display_value
        type
        column {
          title
        }
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!], $columnType: [ColumnType!]) {
    items(ids: $itemIds) {
      id
      name
      column_values(types: $columnType) {
        column { title id }
        ... on FormulaValue {
          display_value
        }
      }
    }
  }
`;

const variables = {
  itemIds: [1234567890, 9876543210],
  columnType: "formula"
};

const response = await mondayApiClient.request(query, variables);

Fields

You can use the following fields to specify what information your FormulaValue implementation will return.

Example response

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "formula_mkl3sp",
            "display_value": "10",
            "type": "formula",
            "column": {
              "title": "Numbers + 5"
            }
          }
        ]
      }
    ]
  }
}

Rate limits

The display_value field for formula columns is subject to the following limits:

• Up to 10,000 formula values per minute
• Maximum of 5 formula columns in one request
• Does not support formulas that reference mirror or connect boards columns

Filter

Formula columns do not support filtering via items_page. Attempting to filter by a formula column returns an invalid rule error.

To filter by formula results, query the display_value for all items and filter client-side, or use a different column that stores the value you need to filter by.

Mutations

Create

Required scope: boards:write

There is no typed create_formula_column mutation. Use the generic create_column mutation with column_type: formula and pass the formula expression in the defaults argument.

mutation {
  create_column(
    board_id: 1234567890
    title: "Total Cost"
    column_type: formula
    defaults: "{\"settings\":{\"formula\":\"{numbers_col} * {rate_col}\"}}"
  ) {
    id
    title
    type
    settings
  }
}

Arguments

Defaults format

The defaults argument accepts a JSON string with the following structure:

{
  "settings": {
    "formula": "{column_id_1} + {column_id_2}"
  }
}

The formula field contains the formula expression. Reference other columns using their column ID wrapped in curly braces (e.g., {numeric_col}). You can use standard formula functions like IF, CONCATENATE, SUM, etc.

Example response

{
  "data": {
    "create_column": {
      "id": "formula_mkl3sp",
      "title": "Total Cost",
      "type": "formula",
      "settings": {"formula": "{numbers_col} * {rate_col}"}
    }
  }
}

Update value

Formula columns cannot be updated via the API. The formula result is computed automatically from the referenced column values.

Attempting to update a formula column returns an error:

• change_simple_column_value: "column type FormulaColumn is not supporting changing the column value with simple column value"
• change_multiple_column_values: "This column type can not be updated or created (client side auto calculated column)"

To change a formula's result, update the source columns that the formula references.

Clear

Formula columns cannot be cleared via the API. To reset a formula's computed value, clear the source columns it references.

Reading column configuration

You can query a formula column's configuration through the column's settings field to inspect the formula expression.

query {
  boards(ids: 1234567890) {
    columns(ids: ["formula_mkl3sp"]) {
      id
      title
      settings
    }
  }
}

settings response structure

The settings field returns a typed JSON object with these keys:

Example settings response

{
  "formula": "{numeric_mkl3sp} + 5"
}

Get column type schema

You can retrieve the JSON schema for the formula column's settings programmatically using the get_column_type_schema query. This returns the structure, validation rules, and available properties for the column's configuration.

query {
  get_column_type_schema(
    type: formula
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {
              "formula": {
                "type": "string",
                "description": "Formula expression"
              },
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              }
            },
            "additionalProperties": false,
            "required": [
              "formula"
            ]
          }
        }
      }
    }
  }
}

The response includes property names, types, constraints (such as max lengths and allowed values), and descriptions for each setting. You can use this to validate column settings, dynamically generate UIs, or give context to AI agents. Learn more about the schema response format.