The date column represents a specific date and optionally a time. It's used for deadlines, milestones, scheduling, and any date-based tracking.

Via the API, the date column supports read, filter, update, and clear operations.

Column Type	Implementation Type	Supported Operations
`date`	`DateValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

Queries

Date columns can be queried through the column_values field on items queries using an inline fragment on DateValue.

🚧
On multi-level boards, date columns with rollup capability require capabilities: [CALCULATED] on the column_values field to return any values. Without it, the API returns an empty array — even for leaf items with static values.
Date rollup columns keep the DateValue type. Use the is_leaf field to distinguish static values (true) from calculated rollup values (false).

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on DateValue {
        id
        date
        time
        text
        value
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on DateValue {
          id
          date
          time
          text
          value
          updated_at
        }
      }
    }
  }
`;

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

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

Fields

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

Field	Description
column `Column!`	The column the value belongs to.
date `String`	The date value in `YYYY-MM-DD` format. Returns `""` if the column has no value.
icon `String`	The selected icon as a string.
id `ID!`	The column's unique identifier.
is_leaf `Boolean!`	Whether this item has no subitems. On multi-level boards with rollup capability, `false` indicates the value is a calculated rollup from child items rather than a static value.
text `String`	The formatted date and optional time in the user's time zone. Returns `""` if the column has no value.
time `String`	The time value converted to the user's time zone. Returns `""` if no time is set.
type `ColumnType!`	The column's type.
updated_at `Date`	The column's last updated date.
value `JSON`	The raw JSON-formatted column value. Contains `date` and `time` in UTC. Returns `null` if the column has no value.

📘
The time field and the time in text are automatically converted to the time zone of the user making the API call. The value field always stores times in UTC.

Example response

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "date",
            "date": "2026-06-15",
            "time": "12:00",
            "text": "2026-06-15 12:00",
            "value": "{\"date\":\"2026-06-15\",\"time\":\"09:00:00\",\"changed_at\":\"2026-03-21T08:36:10.897Z\"}",
            "updated_at": "2026-03-21T08:36:10+00:00"
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by date column values using the items_page object.

Some compare values are dynamic (e.g., "TODAY", "THIS_WEEK") and depend on the time, time zone, date format, and first day of the week of the user making the API call. Others are static (e.g., "EXACT" with a specific date).

📘
The results depend on the time zone, date format, and first day of the week configured in the monday.com profile of the user making the API call.

The table below outlines the supported compare values and their compatible operators.

Compare Value	Description	Operators
`"TODAY"`	Items with today's date.	`any_of`: items dated today `not_any_of`: items with a date that is not today `greater_than`: dates after today `greater_than_or_equals`: dates on or after today `lower_than`: dates before today `lower_than_or_equal`: dates on or before today
`"TOMORROW"`	Items with tomorrow's date.	`any_of`: items dated tomorrow `not_any_of`: items not dated tomorrow `greater_than`: dates after tomorrow `greater_than_or_equals`: dates on or after tomorrow `lower_than`: dates before tomorrow `lower_than_or_equal`: dates on or before tomorrow
`"YESTERDAY"`	Items with yesterday's date.	`any_of`: items dated yesterday `not_any_of`: items not dated yesterday `greater_than`: dates after yesterday `greater_than_or_equals`: dates on or after yesterday `lower_than`: dates before yesterday `lower_than_or_equal`: dates on or before yesterday
`"THIS_WEEK"`	Items dated during the current week. The first day of the week is defined by the account settings of the user making the API call.	`any_of`: dates in the current week `not_any_of`: dates not in the current week `greater_than`: dates after this week `greater_than_or_equals`: dates during or after this week `lower_than`: dates before this week `lower_than_or_equal`: dates during or before this week
`"ONE_WEEK_AGO"`	Items dated during the previous week. The first day of the week is defined by the account settings of the user making the API call.	`any_of`: dates in the previous week `not_any_of`: dates not in the previous week `greater_than`: dates after the previous week `greater_than_or_equals`: dates during or after the previous week `lower_than`: dates before the previous week `lower_than_or_equal`: dates during or before the previous week
`"ONE_WEEK_FROM_NOW"`	Items dated during the upcoming week. The first day of the week is defined by the account settings of the user making the API call.	`any_of`: dates in the upcoming week `not_any_of`: dates not in the upcoming week `greater_than`: dates after the upcoming week `greater_than_or_equals`: dates during or after the upcoming week `lower_than`: dates before the upcoming week `lower_than_or_equal`: dates during or before the upcoming week
`"THIS_MONTH"`	Items dated during the current month.	`any_of`: dates in the current month `not_any_of`: dates not in the current month `greater_than`: dates after the current month `greater_than_or_equals`: dates during or after the current month `lower_than`: dates before the current month `lower_than_or_equal`: dates during or before the current month
`"ONE_MONTH_AGO"`	Items dated during the previous month.	`any_of`: dates in the previous month `not_any_of`: dates not in the previous month `greater_than`: dates after the previous month `greater_than_or_equals`: dates during or after the previous month `lower_than`: dates before the previous month `lower_than_or_equal`: dates during or before the previous month
`"ONE_MONTH_FROM_NOW"`	Items dated during the upcoming month.	`any_of`: dates in the upcoming month `not_any_of`: dates not in the upcoming month `greater_than`: dates after the upcoming month `greater_than_or_equals`: dates during or after the upcoming month `lower_than`: dates before the upcoming month `lower_than_or_equal`: dates during or before the upcoming month
`"PAST_DATETIME"`	Items with a date and time in the past.	`any_of`: past date and time `not_any_of`: date and time not in the past
`"FUTURE_DATETIME"`	Items with a date and time in the future.	`any_of`: future date and time `not_any_of`: date and time not in the future
`"UPCOMING"`	Used with a status column. Returns items not marked as "Done" where the date has not passed. Items with today's date are not considered upcoming.	`any_of`: not "Done" before the date `not_any_of`: "Done" before the date
`"OVERDUE"`	Used with a status column. Returns items not marked as "Done" where the date has passed. Items with today's date will be considered overdue starting the next day.	`any_of`: not "Done" after the date `not_any_of`: "Done" after the date
`"DONE_ON_TIME"`	Used with a status column. Returns items marked as "Done" before the date in the date column.	`any_of`: completed before the date `not_any_of`: not completed before the date
`"DONE_OVERDUE"`	Used with a status column. Returns items marked as "Done" after the date in the date column.	`any_of`: completed after the date `not_any_of`: not completed after the date
Exact dates with `"EXACT"` (e.g., `["EXACT", "2026-07-01"]`)	Use static dates in `YYYY-MM-DD` format, paired with the `"EXACT"` keyword.	`any_of`: items with the specific date `not_any_of`: items without the specific date `greater_than`: dates after the specified date `greater_than_or_equals`: dates on or after the specified date `lower_than`: dates before the specified date `lower_than_or_equal`: dates on or before the specified date `between`: items between two dates (see example below)
`"$$$blank$$$"`	Items with a blank date value.	`any_of`: items with a blank value `not_any_of`: items without a blank value

📘
You can also use the is_empty and is_not_empty operators with an empty compare value ([]) to filter for items with or without a date value set.

Examples

Filter by an exact date

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["EXACT", "2026-07-01"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: [1234567890],
  columnId: "date",
  compareValue: ["EXACT", "2026-07-01"],
  operator: "any_of",
};

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

Filter by multiple compare values

You can combine multiple dynamic and static compare values in a single rule. Each "EXACT" keyword applies to the date that immediately follows it.

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: [
              "EXACT"
              "2026-09-10"
              "TODAY"
              "EXACT"
              "2026-09-11"
              "TOMORROW"
            ]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: [1234567890],
  columnId: "date",
  compareValue: ["EXACT", "2026-09-10", "TODAY", "EXACT", "2026-09-11", "TOMORROW"],
  operator: "any_of",
};

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

Filter for dates during or after the current week

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["THIS_WEEK"]
            operator: greater_than_or_equals
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filter between two dates

The between operator accepts two dates in YYYY-MM-DD format and returns items with dates in that range (inclusive).

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["2026-06-01", "2026-12-31"]
            operator: between
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filter by `"UPCOMING"`

Returns items not marked as "Done" where the date has not passed. Requires a status column on the board.

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["UPCOMING"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filter for empty date values

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: []
            operator: is_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Mutations

Create

Required scope: boards:write

You can create a date column using the generic create_column mutation with column_type: date.

mutation {
  create_column(
    board_id: 1234567890
    column_type: date
    title: "Deadline"
  ) {
    id
    title
  }
}

On multi-level boards, date columns are created with MAX rollup by default. You can specify a different function or disable rollup:

mutation {
  create_column(
    board_id: 1234567890
    column_type: date
    title: "Deadline"
    capabilities: { calculated: { function: MIN } }
  ) {
    id
    title
  }
}

To disable rollup, pass function: NONE:

mutation {
  create_column(
    board_id: 1234567890
    column_type: date
    title: "Reference Date"
    capabilities: { calculated: { function: NONE } }
  ) {
    id
    title
  }
}

Update value

You can update a date column using change_simple_column_value or change_multiple_column_values. You can send values as simple strings or JSON objects, depending on the mutation you choose.

🚧
On multi-level boards, mutations on parent items with calculated rollup values do not return an error — the API returns a success response, but the value is not changed. Update child items instead.

`change_simple_column_value`

Send the date as a string in YYYY-MM-DD format, optionally including time as HH:MM:SS with a space separator. Values should be in UTC, as they are automatically converted to the user's time zone in the UI.

Date only

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "date"
    value: "2026-06-15"
  ) {
    id
  }
}

Date with time

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "date"
    value: "2026-06-15 09:00:00"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValue: String!, $columnId: String!) {
    change_simple_column_value(
      item_id: $itemId
      board_id: $boardId
      column_id: $columnId
      value: $columnValue
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnId: "date",
  columnValue: "2026-06-15 09:00:00",
};

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

`change_multiple_column_values`

Send the date and optional time keys as a JSON object in column_values. The date key uses YYYY-MM-DD format and the time key uses HH:MM:SS format (UTC).

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"date\": {\"date\": \"2026-06-15\", \"time\": \"09:00:00\"}}"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    date: {
      date: "2026-06-15",
      time: "09:00:00"
    }
  }),
};

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

📘
Omit the time key to set a date-only value. When no time is set, the time field returns "" and the raw value stores "time": null.

Set date on item creation

You can set a date value when creating an item by passing the date column value in the column_values argument.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"date\": {\"date\": \"2026-06-15\", \"time\": \"09:00:00\"}}"
  ) {
    id
    name
  }
}

Clear

You can clear a date column using change_simple_column_value or change_multiple_column_values.

`change_simple_column_value`

Pass an empty string in value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "date"
    value: ""
  ) {
    id
  }
}

`change_multiple_column_values`

Pass null in column_values.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"date\": null}"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    date: null
  }),
};

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

Reading column configuration

To understand a date column's display settings, you can query its settings through the column's settings field.

🚧
The settings_str field is deprecated as of API version 2025-10. Use the typed settings object instead, which returns structured JSON rather than a JSON-encoded string.

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

`settings` response structure

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

Key	Type	Description
`show_current_year`	`boolean`	Whether to show the current year in the date display.
`show_week_day`	`boolean`	Whether to show the day of the week.
`show_week_number`	`boolean`	Whether to show the week number.
`show_time_by_default`	`boolean`	Whether to show time by default in the column.
`hide_footer`	`boolean`	Whether to hide the footer in the date picker.
`use_numeric_only_format`	`boolean`	Whether to use numeric-only format (e.g., `03/21/2026` instead of `Mar 21, 2026`).
`show_add_icon`	`boolean`	Whether to show the add icon.
`show_weekends`	`boolean`	Whether to show weekends in the date picker.
`calcType`	`string`	Calculation type for date aggregation. One of `earliestToLatest`, `earliest`, or `latest`.
`date_format`	`string`	Date format configuration.
`time_format`	`string`	Time format configuration.

📘
A date column with default settings returns an empty settings object ({}). Only customized settings appear in the response.

Get column type schema

You can retrieve the JSON schema for the date 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: date
  )
}

{
  "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": {
              "show_current_year": {
                "type": "boolean",
                "description": "Whether to show the current year"
              },
              "show_week_day": {
                "type": "boolean",
                "description": "Whether to show the day of the week"
              },
              "show_week_number": {
                "type": "boolean",
                "description": "Whether to show the week number"
              },
              "show_time_by_default": {
                "type": "boolean",
                "description": "Whether to show time by default"
              },
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              },
              "use_numeric_only_format": {
                "type": "boolean",
                "description": "Whether to use numeric only format"
              },
              "show_add_icon": {
                "type": "boolean",
                "description": "Whether to show the add icon"
              },
              "show_weekends": {
                "type": "boolean",
                "description": "Whether to show weekends"
              },
              "calcType": {
                "type": "string",
                "description": "Calculation type for date column",
                "enum": ["earliestToLatest", "earliest", "latest"]
              },
              "state": {
                "type": "integer",
                "description": "Column state",
                "enum": [0, 1]
              },
              "date_format": {
                "type": "string",
                "description": "Date format configuration"
              },
              "time_format": {
                "type": "string",
                "description": "Time format configuration"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

The response includes property names, types, constraints (such as 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.