The item ID column displays the unique identifier assigned to each item. The column can show either the raw numeric item ID or a custom key format with a configurable prefix and zero-padding.

Via the API, the item ID column supports read and filter operations. It does not support update or clear operations because the value is automatically generated and managed by the system. You can also read an item's ID directly by querying id on any field that returns an items type.

Column Type	Implementation Type	Supported Operations
`item_id`	`ItemIdValue`	Read: Yes Filter: Yes Create: No Update: No Clear: No

Queries

Item ID columns can be queried through the column_values field on items queries using an inline fragment on ItemIdValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on ItemIdValue {
        id
        item_id
        text
        value
        is_leaf
      }
    }
  }
}

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

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

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

Fields

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

Field	Description
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
is_leaf `Boolean!`	Whether the item is a leaf node (has no subitems). Returns `true` for items without subitems.
item_id `ID!`	The item's unique identifier.
text `String`	The column's value as text. Returns the item ID as a string.
type `ColumnType!`	The column's type (`item_id`).
value `JSON`	The column's raw value as a JSON string. Returns `{"item_id": "1234567890"}`.

Example response

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "pulse_id",
            "item_id": "1234567890",
            "text": "1234567890",
            "value": "{\"item_id\":\"1234567890\"}",
            "is_leaf": true
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by their item ID using the items_page object.

Operator	Compare Value	Description
`any_of`	An array of item IDs as strings (e.g., `["1234567890"]`)	Returns items whose ID matches any of the specified values.
`not_any_of`	An array of item IDs as strings (e.g., `["1234567890"]`)	Excludes items whose ID matches any of the specified values.
`contains_terms`	A string item ID value (e.g., `"1234567890"`)	Returns items whose ID contains the specified text.
`is_not_empty`	`[]`	Returns items that have an item ID value set. Since every item has an ID, this effectively returns all items.
`is_empty`	`[]`	Returns items without an item ID value. Since every item has an ID, this always returns an empty result.

Examples

Filter by specific item IDs

This example returns items matching any of the specified IDs.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "pulse_id"
            compare_value: ["9876543210", "1122334455"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Exclude specific item IDs

This example returns all items except those with the specified IDs.

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

Mutations

The item ID column is a read-only, auto-calculated column. It does not support update, clear, or set-on-creation operations.

Attempting to update an item ID column via change_simple_column_value or change_multiple_column_values returns an error:

🚧
The item ID column value cannot be modified through the API. The value is automatically assigned when an item is created.

Reading column configuration

To view an item ID column's configuration, query its 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: ["pulse_id"]) {
      id
      title
      type
      settings
    }
  }
}

`settings` response structure

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

Key	Type	Description
`copyValueSetting`	`string`	How to copy the value: `"text"` (plain ID) or `"link"` (link to the item).
`displayType`	`string`	Display type: `"pulseId"` (raw numeric ID) or `"customKey"` (prefixed key).
`customKeySettings`	`object`	Settings for the custom key display type. Contains `prefix` (string) and `padding` (integer).

Example: Default settings

For a standard item ID column, settings returns an empty object:

{}

Example: Custom key settings

For a column configured with a custom key format:

{
  "displayType": "customKey",
  "customKeySettings": {
    "prefix": "PROJ-",
    "padding": 5
  }
}

This configuration displays item IDs as PROJ-00001, PROJ-00002, etc., in the monday.com UI. The API still returns the raw numeric ID in the item_id and text fields.

Get column type schema

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

{
  "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": {
              "copyValueSetting": {
                "type": "string",
                "description": "How to copy the value (text or link)",
                "enum": [
                  "text",
                  "link"
                ]
              },
              "displayType": {
                "type": "string",
                "description": "Display type for the column value",
                "enum": [
                  "pulseId",
                  "customKey"
                ]
              },
              "customKeySettings": {
                "type": "object",
                "description": "Settings for custom key display type",
                "properties": {
                  "prefix": {
                    "type": "string",
                    "description": "Prefix for the generated key"
                  },
                  "padding": {
                    "type": "integer",
                    "description": "Minimum digits (zero padding)",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              }
            },
            "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.