Every monday.com board has one or more columns, each of which holds a particular type of information. These column values are essentially the board's content, and their inner value structure varies based on their type.

As a developer working with monday.com, it is important to familiarize yourself with the column_values API so you know how to access data within columns. This document will walk you through the available queries to read the column_values object via the API.

Our schema also contains types that extend the ColumnValue type. You can read more in the implementations section of this doc.

Queries

Querying column_values will return metadata about one or a collection of columns. This method accepts one argument and returns an array.

You can only query column_values by nesting it within an items query, so it can't be used at the root.

query {
  items (ids: 1234567890) {
    column_values {
      column {
        id
        title
      }
      id
      type
      value
    }
  }
}
let query = "query { boards (ids: 1234567890) { column_value_v2 { column { id } id type value}}}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to reduce the number of results returned in your column_values query.

ArgumentDescription
ids [String!]The specific columns to return.
types [ColumnType!]The specific type of columns to return.

Fields

You can use the following field(s) to specify what information your column_values query will return.

FieldDescription
column Column!The column the value belongs to.
id ID!The column's unique identifier.
text StringThe text representation of the column's value. Not every column supports the text value.
type ColumnType!The column's type.
value JSONThe column's raw value.

Implementations

Our schema also contains specific types for each column value, such as ButtonValue and StatusValue. These extend the core ColumnValue type, so you can query column-specific fields instead of parsing the column's raw JSON value.

Take the StatusValue type for example. On top of the 5 core fields, it also exposes the column, id, index, is_done, label, label_style, text, type, update_id, updated_at, and value fields specific to the StatusValue type.

Using fragments to get column-specific fields

You can return subfields for a specific column type using GraphQL fragments, or queries that will only run if a specific type is returned. Fragments can help you selectively return column-specific date that doesn't exist on other columns on the board. Each column type has its own fields that you can find in the column types reference documentation.

Here's an example. Notice the ...on StatusValue expression, which will return the label and update_id only on status columns.

query {
  items (ids: 1234567890) {
    column_values {
      value
      type
      ... on StatusValue  { # will only run for status columns
        label
        update_id
      }
    }
  }
}

πŸ“˜

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎