Kolumna śledzenia czasu zapisuje łączny czas poświęcony na element. Dzięki niej zespoły mogą śledzić czas pracy podczas wielu sesji. Użytkownicy mogą uruchamiać i zatrzymywać licznik. Kolumna przechowuje pełną historię sesji śledzenia czasu.

Za pomocą API kolumna śledzenia czasu obsługuje odczyt, filtrowanie i tworzenie. Wartości licznika czasu nie można bezpośrednio zaktualizować ani wyczyścić za pomocą API.

Typ kolumny	Typ implementacji	Obsługiwane operacje
time_tracking	TimeTrackingValue	Odczyt: tak Filtrowanie: tak Tworzenie: tak Aktualizacja: nie Czyszczenie: nie

---

Zapytania

Kolumny śledzenia czasu można odpytywać za pomocą pola column_values obiektu items. W tym celu użyj wbudowanego fragmentu dla 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);

Pola

Za pomocą poniższych pól możesz określić, jakie informacje zwróci implementacja TimeTrackingValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
duration Int	Łączny czas śledzony podczas wszystkich sesji, podany w sekundach. Zwraca 0, jeśli nie śledzono czasu.
history [TimeTrackingHistoryItem!]!	Tablica rekordów sesji śledzenia czasu. Zobacz niżej pola historii.
id ID!	Unikalny identyfikator kolumny.
running Boolean	Informuje, czy licznik czasu jest uruchomiony. Zwraca false, jeśli nigdy go nie uruchomiono lub jest wstrzymany.
started_at Date	Data rozpoczęcia bieżącej sesji. Zwraca null, jeśli licznik nie działa.
text String	Łączny czas w postaci tekstu (np. "02:30:00"). Zwraca "", jeśli nie śledzono czasu.
type ColumnType!	Typ kolumny (time_tracking).
updated_at Date	Data ostatniej aktualizacji wartości kolumny.
value JSON	Surowa wartość kolumny w postaci ciągu JSON.

Pola historii

Każdy wpis w tablicy history reprezentuje pojedynczą sesję śledzenia czasu (TimeTrackingHistoryItem).

Pole	Opis
id ID!	Unikalny identyfikator sesji.
status String!	Status sesji (np. "active", "stopped").
started_at Date	Data rozpoczęcia sesji. Pole jest dostępne tylko wtedy, gdy sesję uruchomiono przyciskiem odtwarzania lub za pomocą automatyzacji.
ended_at Date	Data zakończenia sesji. Pole jest dostępne tylko w przypadku zakończonych sesji.
started_user_id ID	Identyfikator użytkownika, który rozpoczął sesję.
ended_user_id ID	Identyfikator użytkownika, który zakończył sesję.
created_at Date!	Data utworzenia rekordu sesji.
updated_at Date	Data ostatniej aktualizacji sesji.
manually_entered_start_date Boolean!	Informuje, czy datę rozpoczęcia wpisano ręcznie.
manually_entered_start_time Boolean!	Informuje, czy godzinę rozpoczęcia wpisano ręcznie.
manually_entered_end_date Boolean!	Informuje, czy datę zakończenia wpisano ręcznie.
manually_entered_end_time Boolean!	Informuje, czy godzinę zakończenia wpisano ręcznie.

Przykładowa odpowiedź

{
  "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"
              }
            ]
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

Możesz filtrować elementy według stanu śledzenia czasu za pomocą obiektu items_page. Filtr sprawdza, czy licznik czasu jest uruchomiony.

Operator	Wartość porównania	Opis
any_of	Tablica wartości stanu	Zwraca elementy pasujące do określonego stanu licznika czasu. Zobacz niżej wartości porównania.
not_any_of	Tablica wartości stanu	Wyklucza elementy pasujące do określonego stanu licznika czasu.

Wartości porównania

Wartość	Opis
1	Licznik czasu jest wstrzymany lub pusty (nie działa)
2	Licznik czasu jest uruchomiony

Przykłady

Filtrowanie według uruchomionych liczników czasu

Ten przykład zwraca elementy z aktywnym licznikiem śledzenia czasu.

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

Filtrowanie według wstrzymanych lub pustych liczników czasu

Ten przykład zwraca elementy, w których licznik czasu nie jest uruchomiony.

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

---

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Mutacja create_column tworzy nową kolumnę śledzenia czasu za pomocą API. Możesz określić, które pola mają zostać zwrócone w odpowiedzi mutacji.

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

---

Odczytywanie konfiguracji kolumny

Aby odczytać konfigurację kolumny śledzenia czasu, pobierz jej ustawienia za pomocą pola settings kolumny.

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

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON zawierający następujące klucze:

Klucz	Typ	Opis
showSeconds	boolean	Informuje, czy w wyświetlanym czasie mają być widoczne sekundy.

Przykładowa odpowiedź settings

{}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny śledzenia czasu za pomocą zapytania get_column_type_schema. Zwraca ono strukturę, reguły walidacji i dostępne właściwości konfiguracji kolumny.

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

Odpowiedź zawiera nazwy właściwości, typy, ograniczenia (takie jak maksymalna długość i dozwolone wartości) oraz opisy poszczególnych ustawień. Możesz użyć tych informacji do walidacji ustawień kolumny, dynamicznego generowania interfejsów użytkownika lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.