Tags

Learn how to query monday account tags using the platform API

Tags are objects that help you group items from different groups or different boards throughout your account by a consistent keyword. Public tags appear on main boards and are accessible to all member and viewer-level users by default, while private tags only appear on private or shareable boards. They are created and displayed in the tags column.

Queries

You can use the tags query to retrieve tag data via the API.

  • Required scope: tags:read
  • Returns an array containing metadata about one or a collection of the account's public tags
  • Can be queried directly at the root or nested within a boards (only returns tags stored on private or shareable boards)
query {
  boards(ids: 1234567890) {
    tags {
      id
    }	
  }
}

👍

Pro tip

Before assigning a tag to an item, use the tags query to ensure it exists.

Arguments

You can use the following argument to reduce the number of results returned in your tags query.

ArgumentDescription
ids [ID!]The unique identifiers of specific tags to return. Returns an empty result for private tag IDs.

Fields

You can use the following fields to specify what information your tags query will return.

FieldDescription
color String!The tag's color.
id Int!The tag's unique identifier.
name String!The tag's name.

Mutations

The API allows you to create tags using the following mutation.

Create or get tag

Required scope: boards:write

The create_or_get_tag mutation creates new tags or retrieves their data if they already exist via the API. You can specify which fields to return in the mutation response.

👍 After creating a tag, it only appears in the UI after being used at least once.

mutation {
  create_or_get_tag(tag_name: "My tag") {
    id
  }
}
let query = "mutation { create_or_get_tag (tag_name: \"amazing\") { id } }";

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 arguments to define the new or existing tag's characteristics.

ArgumentDescription
board_id IDThe unique identifier of the shareable or private board where the tag should be created. If you want to create a public tag, do not use this argument.
tag_name StringThe new tag's name.

Update tags column

The change_column_value mutation allows you to change a column value via the API. Check out the tags column type reference for the correct formatting!