The subitems column displays the subitems nested under a parent item. It provides a way to break items into smaller, actionable tasks while keeping them linked to their parent.

The subitems column is read-only — you cannot write values to it directly. Instead, manage subitems through the create_subitem and delete_item mutations.

Column Type	Implementation Type	Supported Operations
`subtasks`	`SubtasksValue`	Read: Yes Filter: Yes Create: Yes (column only) Update: No (use `create_subitem` / `delete_item`) Clear: No

Queries

Subitems columns can be queried through the column_values field on items using an inline fragment. Values for the subitems column are of the SubtasksValue type.

The column's behavior depends on whether the queried item is a parent or a leaf:

Parent items (items with subitems): is_leaf is false, subitems and subitems_ids are populated
Leaf items (items without subitems, or subitems themselves): is_leaf is true, subitems and subitems_ids are empty

SubtasksValue

query {
  items(ids: [1234567890]) {
    name
    column_values {
      ... on SubtasksValue {
        id
        display_value
        is_leaf
        subitems_ids
        subitems {
          id
          name
        }
        text
        type
        value
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on SubtasksValue {
          id
          display_value
          is_leaf
          subitems_ids
          subitems {
            id
            name
          }
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890] };

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

Fields

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

Field	Description
column `Column!`	The column the value belongs to.
display_value `String!`	A comma-separated string of all subitem names. Returns an empty string if the item has no subitems.
id `ID!`	The column's unique identifier.
is_leaf `Boolean!`	Whether this item is a leaf node (has no subitems). Returns `true` for subitems and items without subitems.
subitems `[Item!]!`	The item's subitems. Returns an empty array if the item has no subitems.
subitems_ids `[ID!]!`	An array of subitem IDs. Returns an empty array if the item has no subitems.
text `String`	The column's value as text. Always returns `null` for subitems columns.
type `ColumnType!`	The column's type (`subtasks`).
value `JSON`	The column's raw value in JSON format. Always returns `null` for subitems columns.

Example response (parent item)

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "subitems",
            "display_value": "Design mockup, Write specs, Implement feature",
            "is_leaf": false,
            "subitems_ids": ["1234567891", "1234567892", "1234567893"],
            "subitems": [
              { "id": "1234567891", "name": "Design mockup" },
              { "id": "1234567892", "name": "Write specs" },
              { "id": "1234567893", "name": "Implement feature" }
            ],
            "text": null,
            "type": "subtasks",
            "value": null
          }
        ]
      }
    ]
  }
}

Example response (leaf item)

{
  "data": {
    "items": [
      {
        "name": "Design mockup",
        "column_values": [
          {
            "id": "subitems",
            "display_value": "",
            "is_leaf": true,
            "subitems_ids": [],
            "subitems": [],
            "text": null,
            "type": "subtasks",
            "value": null
          }
        ]
      }
    ]
  }
}

📘
The subitems field on SubtasksValue returns full Item objects, so you can query any item field (column values, groups, etc.) on each subitem within the same request.

Querying subitems directly

You can also access subitems through the subitems field on the Item type, without using the subitems column value:

query {
  items(ids: [1234567890]) {
    name
    subitems {
      id
      name
      column_values {
        id
        text
      }
    }
  }
}

Filter

You can filter items by whether they have subitems using the items_page object.

Operator	Compare Value	Description
`is_empty`	`[]`	Returns items that have no subitems.
`is_not_empty`	`[]`	Returns items that have at least one subitem.

Examples

Filter for items with subitems

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

Filter for items without subitems

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

Mutations

The subitems column is read-only — you cannot set or clear its value directly. Instead, use the following mutations to manage subitems:

Create column

Required scope: boards:write

You can create a subitems column using the generic create_column mutation. There is no typed create_subtasks_column mutation.

mutation {
  create_column(
    board_id: 1234567890
    title: "Subitems"
    column_type: subtasks
  ) {
    id
    title
    type
  }
}

🚧
Each board can only have one subitems column. Attempting to create a second one will return an error.

Create a subitem

Required scope: boards:write

Use the create_subitem mutation to add a subitem under a parent item. The subitem will automatically appear in the parent's subitems column.

mutation {
  create_subitem(
    parent_item_id: 1234567890
    item_name: "Design mockup"
  ) {
    id
    name
    board {
      id
    }
  }
}

const query = `
  mutation ($parentItemId: ID!, $itemName: String!) {
    create_subitem(
      parent_item_id: $parentItemId
      item_name: $itemName
    ) {
      id
      name
    }
  }
`;

const variables = {
  parentItemId: 1234567890,
  itemName: "Design mockup"
};

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

Arguments

Argument	Type	Description
parent_item_id	`ID!`	The parent item's unique identifier.
item_name	`String!`	The new subitem's name.
column_values	`JSON`	Column values for the new subitem as a JSON string.
create_labels_if_missing	`Boolean`	Create status/dropdown labels if they don't exist. Requires permission to change board structure.

Create a subitem with column values

mutation {
  create_subitem(
    parent_item_id: 1234567890
    item_name: "Implement login flow"
    column_values: "{\"status\": {\"label\": \"Working on it\"}, \"person\": {\"personsAndTeams\": [{\"id\": 9876543, \"kind\": \"person\"}]}}"
  ) {
    id
    name
  }
}

Delete a subitem

Required scope: boards:write

Use the delete_item mutation to remove a subitem. This also removes it from the parent's subitems column.

mutation {
  delete_item(item_id: 9876543210) {
    id
  }
}

📘
You cannot update the subitems column value directly using change_simple_column_value or change_multiple_column_values. The API will return an error if you attempt to write to this column.

Reading column configuration

You can query the subitems column's 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: ["subitems"]) {
      id
      title
      settings
    }
  }
}

`settings` response structure

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

Key	Type	Description
`allowMultipleItems`	`boolean`	Whether the column allows multiple subitems.
`itemTypeName`	`string`	The internal type name for subitems in this column.
`displayType`	`string`	How subitems are displayed. Typically `"BOARD_INLINE"`.
`boardIds`	`number[]`	The board IDs associated with the subitems.

Example `settings` response

{
  "allowMultipleItems": true,
  "itemTypeName": "column.subtasks.title",
  "displayType": "BOARD_INLINE",
  "boardIds": [1234567890]
}

Get column type schema

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

{
  "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": {},
            "additionalProperties": false
          }
        }
      }
    }
  }
}

The subitems column has no configurable settings via the schema. The column's behavior is managed through the board's structure and the subitem mutations.

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.