Guides
Apps DocsCommunityNeed Help?
Start typing to search…

Working with the dependency column

Learn how to read, set, and manage item dependencies via the monday.com API, including column configuration and dependency modes.

The dependency column lets you define relationships between items on the same board — for example, "Task B cannot start until Task A is finished." These relationships can be visualized in Gantt views, drive timeline and date automations, and power dependency-based automations.

This guide walks through how to read dependency values, set them via mutation, understand column configuration modes, and filter items by their dependencies.

Prerequisites

  • A board with a dependency column
  • Item IDs for the items you want to link
  • The dependency column's ID (e.g., "dependent_on")

To find your column ID, query the board's columns:

query {
  boards(ids: [1234567890]) {
    columns {
      id
      title
      type
    }
  }
}

Reading dependency values

Query the dependency column using an inline fragment on DependencyValue:

query {
  items(ids: [9876543210]) {
    name
    column_values(types: dependency) {
      ... on DependencyValue {
        id
        display_value
        linked_item_ids
        linked_items {
          id
          name
        }
        updated_at
      }
    }
  }
}
const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values(types: dependency) {
        ... on DependencyValue {
          id
          display_value
          linked_item_ids
          linked_items {
            id
            name
          }
          updated_at
        }
      }
    }
  }
`;

const variables = { itemIds: [9876543210] };
const response = await mondayApiClient.request(query, variables);

Key fields:

FieldDescription
display_valueComma-separated names of dependent items. Empty string if no dependencies.
linked_item_idsArray of item IDs this item depends on.
linked_itemsFull item objects (id + name) for each dependency.
updated_atWhen the dependency was last changed. null if never set.
📘

The text and value fields always return null for dependency columns. Use linked_item_ids or linked_items for dependency data.

Setting dependencies

Use change_multiple_column_values to set dependencies. Pass an item_ids array containing the IDs of items that this item depends on.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dependent_on\": {\"item_ids\": [\"1111111111\", \"2222222222\"]}}"
  ) {
    id
  }
}
const mutation = `
  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({
    dependent_on: {
      item_ids: ["1111111111", "2222222222"]
    }
  }),
};

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

Setting dependencies replaces the entire list. To add a dependency without removing existing ones, first query linked_item_ids, append the new ID, then send the full updated list.

Adding a dependency without overwriting existing ones

// 1. Read current dependencies
const readQuery = `
  query ($itemId: [ID!]) {
    items(ids: $itemId) {
      column_values(types: dependency) {
        ... on DependencyValue {
          linked_item_ids
        }
      }
    }
  }
`;

const readResult = await mondayApiClient.request(readQuery, { itemId: [9876543210] });
const existing = readResult.data.items[0].column_values[0].linked_item_ids;

// 2. Append new dependency and write back
const newId = "3333333333";
const updatedIds = [...existing, newId];

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

await mondayApiClient.request(updateMutation, {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({ dependent_on: { item_ids: updatedIds } }),
});

Setting dependencies on item creation

You can set dependency values at the time an item is created:

mutation {
  create_item(
    board_id: 1234567890
    item_name: "Deploy backend"
    column_values: "{\"dependent_on\": {\"item_ids\": [\"9876543210\"]}}"
  ) {
    id
    name
  }
}

Clearing dependencies

Pass null or an empty object as the column value to remove all dependencies:

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

Reading column configuration

To inspect how a dependency column is configured, query the settings field on the column:

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

Example response:

{
  "id": "dependent_on",
  "title": "Dependency",
  "settings": {
    "boardIds": [1234567890],
    "dependencyNewInfra": true,
    "allowMultipleItems": true,
    "dependency_mode": "flexible"
  }
}

Dependency modes

The dependency_mode controls what happens to a linked Date or Timeline column when a dependency is completed:

ModeBehavior
flexibleThe linked date or timeline shifts automatically, but allows some overlap between predecessor and successor items.
strictStrict sequencing is enforced — the dependent item cannot start until its predecessor is fully complete.
no_actionNo automatic adjustment is made to dates or timelines when a dependency's status changes.
📘

The dependency_mode only affects boards that also have a Date or Timeline column. Without one, the mode has no functional impact.

Filtering by dependency

Use items_page to filter items by dependency state. The dependency column supports four operators:

OperatorCompare valueReturns
any_ofArray of item IDsItems that depend on any of the specified items.
not_any_ofArray of item IDsItems that do not depend on any of the specified items.
is_empty[]Items with no dependencies set.
is_not_empty[]Items with at least one dependency set.

Find all items that depend on a specific item

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

Find all items with no dependencies

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

Dependency relationship types

monday.com supports four dependency relationship types that define how two items relate to each other:

TypeAbbreviationDescription
Finish-to-startFSItem B cannot start until Item A finishes. The most common type.
Start-to-startSSItem B cannot start until Item A starts.
Finish-to-finishFFItem B cannot finish until Item A finishes.
Start-to-finishSFItem B cannot finish until Item A starts. Rarely used.

These types are set per dependency link in the monday.com UI when choosing dependencies.

🚧

Dependency relationship types are not currently exposed by the API. The DependencyValue type returns which items are linked but not the relationship type (FS, SS, FF, SF) between them. Use the monday.com UI to configure relationship types.

Common patterns

Build a dependency chain readout

This query retrieves all items on a board with their full dependency data — useful for visualizing chains or validating ordering:

query {
  boards(ids: [1234567890]) {
    items_page {
      items {
        id
        name
        column_values(types: dependency) {
          ... on DependencyValue {
            linked_item_ids
            display_value
          }
        }
      }
    }
  }
}

Validate no circular dependencies

The API does not enforce cycle detection. If you're building tooling that creates dependencies programmatically, implement cycle detection client-side by traversing the linked_item_ids graph before writing changes.

Related

Updated about 3 hours ago