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.
Argument | Description |
---|---|
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.
Field | Description |
---|---|
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.
Argument | Description |
---|---|
board_id ID | The 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 String | The 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!