Learn how to filter by, read, update, and clear the timeline column on monday boards using the platform API
The timeline column stores a range of dates, allowing items to represent longer time spans (e.g., project durations).
Via the API, the timeline column supports read, filter, update, and clear operations.
Column Type | Implementation Type | Supported Operations |
|---|---|---|
|
|
|
Queries
Timeline columns can be queried through the column_values field on items queries using an inline fragment on TimelineValue.
query {
items(ids: [1234567890, 9876543210]) {
column_values {
... on TimelineValue {
from
to
}
}
}
}Fields
You can use the following fields to specify what information your TimelineValue implementation will return.
| Field | Description |
|---|---|
column Column! | The column the value belongs to. |
from Date | The timeline's start date. |
id ID! | The column's unique identifier. |
text String | The date range as text (YYYY-MM-DD format). Returns "" if the column has an empty value. |
to Date | The timeline's end date. |
type ColumnType! | The column's type. |
updated_at Date | The column's last updated date. |
value JSON | The column's JSON-formatted raw value. |
visualization_string String | The column's visualization type. |
Filter
You can filter items by timeline values using the items_page object. The timeline column supports the following operators:
| Operators | Compare Values | Compare Attributes |
|---|---|---|
any_of | "CURRENT", "DUE_TODAY", "FUTURE_TIMELINE", "PAST_TIMELINE", "DONE_ON_TIME", "OVERDUE", "DONE_OVERDUE", "MILESTONE", "$$$blank$$$" | — |
not_any_of | "CURRENT", "DUE_TODAY", "FUTURE_TIMELINE", "PAST_TIMELINE", "DONE_ON_TIME", "OVERDUE", "DONE_OVERDUE", "MILESTONE", "$$$blank$$$" | — |
is_empty | [] | — |
is_not_empty | [] | — |
greater_than | "TODAY", "TOMORROW", "YESTERDAY", "THIS_WEEK", "ONE_WEEK_AGO", "ONE_WEEK_FROM_NOW", "THIS_MONTH", "ONE_MONTH_AGO", "ONE_MONTH_FROM_NOW", "PAST_DATETIME", "FUTURE_DATETIME", "UPCOMING", "OVERDUE", "DONE_ON_TIME", "DONE_OVERDUE", "EXACT" | "START_DATE", "END_DATE" |
greater_than_or_equals | "TODAY", "TOMORROW", "YESTERDAY", "THIS_WEEK", "ONE_WEEK_AGO", "ONE_WEEK_FROM_NOW", "THIS_MONTH", "ONE_MONTH_AGO", "ONE_MONTH_FROM_NOW", "PAST_DATETIME", "FUTURE_DATETIME", "UPCOMING", "OVERDUE", "DONE_ON_TIME", "DONE_OVERDUE", "EXACT" | "START_DATE", "END_DATE" |
lower_than | "TODAY", "TOMORROW", "YESTERDAY", "THIS_WEEK", "ONE_WEEK_AGO", "ONE_WEEK_FROM_NOW", "THIS_MONTH", "ONE_MONTH_AGO", "ONE_MONTH_FROM_NOW", "PAST_DATETIME", "FUTURE_DATETIME", "UPCOMING", "OVERDUE", "DONE_ON_TIME", "DONE_OVERDUE", "EXACT" | "START_DATE", "END_DATE" |
lower_than_or_equal | "TODAY", "TOMORROW", "YESTERDAY", "THIS_WEEK", "ONE_WEEK_AGO", "ONE_WEEK_FROM_NOW", "THIS_MONTH", "ONE_MONTH_AGO", "ONE_MONTH_FROM_NOW", "PAST_DATETIME", "FUTURE_DATETIME", "UPCOMING", "OVERDUE", "DONE_ON_TIME", "DONE_OVERDUE", "EXACT" | "START_DATE", "END_DATE" |
between | "TODAY", "TOMORROW", "YESTERDAY", "THIS_WEEK", "ONE_WEEK_AGO", "ONE_WEEK_FROM_NOW", "THIS_MONTH", "ONE_MONTH_AGO", "ONE_MONTH_FROM_NOW", "PAST_DATETIME", "FUTURE_DATETIME", "UPCOMING", "OVERDUE", "DONE_ON_TIME", "DONE_OVERDUE", "EXACT" | "START_DATE", "END_DATE" |
Examples
Filter items with an end date in the current week or later
query {
boards(ids: 1234567890) {
items_page(
query_params: {
rules: [
{
column_id: "timeline"
compare_value: "THIS_WEEK"
compare_attribute: "END_DATE"
operator: greater_than_or_equals
}
]
}
) {
items { id }
}
}
}Filter items with a start date on or before March 1st, 2024
query {
boards(ids: 1234567890) {
items_page(
query_params: {
rules: [
{
column_id: "timeline"
compare_value: ["EXACT", "2024-03-01"]
compare_attribute: "START_DATE"
operator: lower_than_or_equal
}
]
}
) {
items { id }
}
}
}Mutations
Update
You can update a timeline column using change_multiple_column_values by passing a JSON object.
Send the from and to keys (YYYY-MM-DD format) as a JSON object in column_values.
mutation {
change_multiple_column_values(
item_id: 9876543210
board_id: 1234567890
column_values: "{\"timeline\": {\"from\": \"2019-06-03\", \"to\": \"2019-06-07\"}}"
) {
id
}
}Clear
You can clear a timeline column using change_multiple_column_values by passing null or an empty object in column_values.
mutation {
change_multiple_column_values(
item_id: 9876543210
board_id: 1234567890
column_values: "{\"timeline\": null}"
) {
id
}
}