API Reference
Apps DocsCommunityNeed Help?

Time Tracking

Learn how to read, filter, and create the time tracking column on monday boards using the platform API

The time tracking column records the total time spent on an item, allowing teams to track work duration across multiple sessions. Users can start and stop the timer, and the column stores a complete history of tracking sessions.

Via the API, the time tracking column supports read, filter, and create operations. Timer values cannot be updated or cleared directly through the API.

Column TypeImplementation TypeSupported Operations
time_trackingTimeTrackingValue
  • Read: Yes
  • Filter: Yes
  • Create: Yes
  • Update: No
  • Clear: No

Queries

Time tracking columns can be queried through the column_values field on items using an inline fragment on TimeTrackingValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on TimeTrackingValue {
        id
        duration
        running
        started_at
        updated_at
        history {
          id
          status
          started_at
          ended_at
          started_user_id
          ended_user_id
          created_at
        }
      }
    }
  }
}
const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on TimeTrackingValue {
          id
          duration
          running
          started_at
          updated_at
          history {
            id
            status
            started_at
            ended_at
            started_user_id
          }
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

const response = await mondayApiClient.request(query, variables);

Fields

You can use the following fields to specify what information your TimeTrackingValue implementation will return.

FieldDescription
column Column!The column the value belongs to.
duration IntThe total tracked time in seconds across all sessions. Returns 0 if no time has been tracked.
history [TimeTrackingHistoryItem!]!An array of tracking session records. See history fields below.
id ID!The column's unique identifier.
running BooleanWhether the timer is currently running. Returns false if never started or paused.
started_at DateThe date when the currently running session was started. Returns null if not running.
text StringThe total duration as text (e.g., "02:30:00"). Returns "" if no time has been tracked.
type ColumnType!The column's type (time_tracking).
updated_at DateThe date when the column value was last updated.
value JSONThe column's raw value as a JSON string.

History fields

Each entry in the history array represents a single tracking session (a TimeTrackingHistoryItem).

FieldDescription
id ID!A unique session identifier.
status String!The status of the session (e.g., "active", "stopped").
started_at DateWhen the session was started. Only present if started via the play button or automation.
ended_at DateWhen the session ended. Only present for completed sessions.
started_user_id IDThe ID of the user who started the session.
ended_user_id IDThe ID of the user who ended the session.
created_at Date!When the session record was created.
updated_at DateWhen the session was last updated.
manually_entered_start_date Boolean!Whether the start date was manually entered.
manually_entered_start_time Boolean!Whether the start time was manually entered.
manually_entered_end_date Boolean!Whether the end date was manually entered.
manually_entered_end_time Boolean!Whether the end time was manually entered.

Example response

{
  "data": {
    "items": [
      {
        "name": "Design Review",
        "column_values": [
          {
            "id": "time_tracking",
            "duration": 5400,
            "running": false,
            "started_at": null,
            "updated_at": "2026-03-20T14:30:00Z",
            "history": [
              {
                "id": "abc123",
                "status": "stopped",
                "started_at": "2026-03-20T10:00:00Z",
                "ended_at": "2026-03-20T11:30:00Z",
                "started_user_id": "1234567",
                "ended_user_id": "1234567",
                "created_at": "2026-03-20T10:00:00Z"
              }
            ]
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by time tracking status using the items_page object. The filter matches against the timer's running state.

OperatorCompare ValueDescription
any_ofAn array of state valuesReturns items matching the specified timer state. See compare values below.
not_any_ofAn array of state valuesExcludes items matching the specified timer state.

Compare values

ValueDescription
1Timer is paused or empty (not running)
2Timer is currently running

Examples

Filter for running timers

This example returns items with an actively running time tracker.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "time_tracking"
            compare_value: [2]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on TimeTrackingValue {
            duration
            running
            started_at
          }
        }
      }
    }
  }
}

Filter for paused or empty timers

This example returns items where the timer is not running.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "time_tracking"
            compare_value: [1]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Mutations

Create

Required scope: boards:write

The create_column mutation creates a new time tracking column via the API. You can specify which fields to return in the mutation response.

mutation {
  create_column(
    board_id: 1234567890
    title: "Time Spent"
    column_type: time_tracking
  ) {
    id
    title
    type
  }
}
🚧

Time tracking column values cannot be updated or cleared via the API. The timer can only be started, stopped, and managed through the monday.com UI or automations.

Reading column configuration

To read a time tracking column's configuration, query its settings through the column's settings field.

🚧

The settings_str field is deprecated as of API version 2025-10. Use the typed settings object instead, which returns structured JSON rather than a JSON-encoded string.

query {
  boards(ids: 1234567890) {
    columns(ids: ["time_tracking"]) {
      id
      title
      settings
    }
  }
}

settings response structure

The settings field returns a typed JSON object with these keys:

KeyTypeDescription
showSecondsbooleanWhether to show seconds in the duration display.

Example settings response

{}
📘

Most time tracking columns return an empty settings object. The showSeconds option is only present when explicitly configured.

Get column type schema

You can retrieve the JSON schema for the time tracking column's settings programmatically using the get_column_type_schema query. This returns the structure, validation rules, and available properties for the column's configuration.

query {
  get_column_type_schema(
    type: time_tracking
  )
}
{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {
              "showSeconds": {
                "type": "boolean",
                "description": "Whether to show seconds in the duration UI"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

The response includes property names, types, constraints (such as max lengths and allowed values), and descriptions for each setting. You can use this to validate column settings, dynamically generate UIs, or give context to AI agents. Learn more about the schema response format.


Updated 4 months ago

Updated 4 months ago