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
`timeline`	`TimelineValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

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
  }
}