The week column represents a week-long date range. The start and end dates adapt to the first-day-of-week settings configured in the monday.com account.

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

Column Type	Implementation Type	Supported Operations
`week`	`WeekValue`	Read: Yes Filter: Yes Create: Yes Update: Yes Clear: Yes

Queries

Week columns can be queried through the column_values field on items using an inline fragment on WeekValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on WeekValue {
        id
        start_date
        end_date
        text
        value
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on WeekValue {
          id
          start_date
          end_date
          text
          value
        }
      }
    }
  }
`;

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

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

Fields

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

Field	Description
column `Column!`	The column the value belongs to.
end_date `Date`	The week's end date. Returns `null` if no week is set.
id `ID!`	The column's unique identifier.
start_date `Date`	The week's start date. Returns `null` if no week is set.
text `String`	The week range as text (e.g., `"2026-03-16 - 2026-03-22"`). Returns `""` if empty.
type `ColumnType!`	The column's type (`week`).
value `JSON`	The column's raw value as a JSON string. Contains `week` object with `startDate` and `endDate`.

Example response

{
  "data": {
    "items": [
      {
        "name": "Sprint 12",
        "column_values": [
          {
            "id": "week",
            "start_date": "2026-03-16",
            "end_date": "2026-03-22",
            "text": "2026-03-16 - 2026-03-22",
            "value": "{\"week\":{\"startDate\":\"2026-03-16\",\"endDate\":\"2026-03-22\"}}"
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by week values using the items_page object. The week column supports relative time-based and empty/non-empty filtering.

Operator	Compare Value	Description
`any_of`	An array of relative week identifiers	Returns items whose week matches any of the specified periods. See compare values below.
`not_any_of`	An array of relative week identifiers	Excludes items whose week matches any of the specified periods.
`is_empty`	`[]`	Returns items with no week value set.
`is_not_empty`	`[]`	Returns items that have a week value set.

Compare values

Value	Description
`"THIS_WEEK"`	The current week
`"NEXT_WEEKS"`	All upcoming weeks
`"PAST_WEEKS"`	All previous weeks

Examples

Filter for current week

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "week"
            compare_value: ["THIS_WEEK"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on WeekValue {
            start_date
            end_date
          }
        }
      }
    }
  }
}

Filter for past weeks

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

Mutations

Create

Required scope: boards:write

The create_column mutation creates a new week column via the API.

mutation {
  create_column(
    board_id: 1234567890
    title: "Sprint Week"
    column_type: week
  ) {
    id
    title
    type
  }
}

Update value

You can update a week column using change_multiple_column_values by passing a JSON object with startDate and endDate in YYYY-MM-DD format.

🚧
The dates must span exactly one week (7 days) and the startDate must align with the account's first-day-of-week setting. If the dates don't form a valid week, the API will return an error.

`change_multiple_column_values`

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"week\": {\"week\": {\"startDate\": \"2026-03-16\", \"endDate\": \"2026-03-22\"}}}"
  ) {
    id
    name
  }
}

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

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    week: {
      week: {
        startDate: "2026-03-16",
        endDate: "2026-03-22"
      }
    }
  })
};

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

Set week on item creation

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

mutation {
  create_item(
    board_id: 1234567890
    item_name: "Sprint 12"
    column_values: "{\"week\": {\"week\": {\"startDate\": \"2026-03-16\", \"endDate\": \"2026-03-22\"}}}"
  ) {
    id
    name
  }
}

Clear

You can clear a week column using change_multiple_column_values by passing null or an empty object.

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

Reading column configuration

To read a week column's configuration, 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: ["week"]) {
      id
      title
      settings
    }
  }
}

`settings` response structure

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

Key	Type	Description
`color`	`string`	Hex color code for the week column display (e.g., `"#037f4c"`). Must be exactly 7 characters.

Example `settings` response

{
  "color": "#037f4c"
}

Get column type schema

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

{
  "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": {
              "color": {
                "type": "string",
                "description": "Hex color code for the week column display (e.g., #037f4c)",
                "minLength": 7,
                "maxLength": 7
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

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.

Queries

Fields

Example response

Filter

Compare values

Examples

Filter for current week

Filter for past weeks

Mutations

Create

Update value

change_multiple_column_values

Set week on item creation

Clear

Reading column configuration

settings response structure

Example settings response

Get column type schema

`change_multiple_column_values`

`settings` response structure

Example `settings` response