---

Kolumna statusu (status column) wyświetla etykiety określające stan elementu. Najczęściej służy do obsługi przepływów pracy, monitorowania postępów projektu i wizualnego przedstawiania statusu. Każda kolumna statusu zawiera zestaw etykiet, kolorów i indeksów.

Za pomocą API można odczytywać, filtrować, tworzyć, aktualizować i czyścić wartości kolumny statusu.

Typ kolumny	Typ implementacji	Obsługiwane operacje
status	StatusValue	Odczyt: Tak Filtrowanie: Tak Tworzenie: Tak Aktualizowanie: Tak Czyszczenie: Tak

---

Zapytania

Kolumny statusu możesz odpytywać za pomocą pola column_values obiektu items, używając fragmentu inline.

W zależności od typu tablicy API zwraca jeden z dwóch typów wartości:

• Tablice klasyczne: typ StatusValue
• Tablice wielopoziomowe: typ BatteryValue

Wpływa to na sposób odpytywania i interpretowania danych, jak pokazano w poniższych przykładach.

StatusValue (tablice klasyczne)

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on StatusValue {
        id
        index
        label
        text
        is_done
        label_style {
          color
          border
        }
        value
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on StatusValue {
          id
          index
          label
          text
          is_done
          label_style {
            color
            border
          }
          value
        }
      }
    }
  }
`;

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

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

Pola

Możesz użyć następujących pól, aby określić, jakie informacje zwróci implementacja StatusValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
id ID!	Unikalny identyfikator kolumny.
index Int	Identyfikator etykiety statusu (używany podczas aktualizowania). Zwraca null, jeśli status jest pusty.
is_done Boolean	Określa, czy status jest oznaczony jako ukończony.
label String	Bieżąca etykieta wyświetlana dla elementu. Zwraca null, jeśli status jest pusty.
label_style StatusLabelStyle	Kolor i obramowanie etykiety. Zawiera color (kod hex) i border (kod hex).
text String	Wartość kolumny w postaci tekstu. Zwraca null, jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny.
update_id ID	Aktualizacja powiązana z tym statusem (jeśli istnieje).
updated_at Date	Data ostatniej aktualizacji kolumny.
value JSON	Surowa wartość kolumny w postaci ciągu JSON. Zwraca {"index": N}, gdzie N to identyfikator etykiety.
is_leaf Boolean!	Określa, czy element nie ma podelementów. Zwraca false, gdy element ma podelementy na tablicy klasycznej lub wielopoziomowej.

StatusLabelStyle

Obiekt zawierający właściwości stylu etykiety statusu.

Pole	Typ	Opis
border	String!	Kod koloru Hex obramowania etykiety.
color	String!	Kod koloru Hex etykiety.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "status",
            "index": 1,
            "label": "Done",
            "text": "Done",
            "is_done": true,
            "label_style": {
              "color": "#00c875",
              "border": "#00b461"
            },
            "value": "{\"index\":1}",
            "updated_at": "2026-03-20T12:00:00Z"
          }
        ]
      }
    ]
  }
}

BatteryValue (tablice wielopoziomowe)

Na tablicach wielopoziomowych kolumny statusu z funkcją agregacji zwracają typ BatteryValue zamiast StatusValue. Dotyczy to wszystkich elementów - zarówno nadrzędnych z obliczonymi wartościami, jak i końcowych ze statycznymi wartościami. W przypadku elementów końcowych tablica battery_value zawiera jeden wpis reprezentujący status danego elementu. W przypadku elementów nadrzędnych zawiera zagregowaną liczbę statusów wszystkich elementów podrzędnych.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values(capabilities: [CALCULATED]) {
      ... on BatteryValue {
        id
        text
        is_leaf
        battery_value {
          key
          count
        }
      }
    }
  }
}

Pola

Możesz użyć następujących pól, aby określić, jakie informacje zwróci implementacja BatteryValue.

Pole	Opis	Obsługiwane pola
battery_value [BatteryValueItem!]!	Indeksy kolumny i liczba ich wystąpień.	count Int! key ID!
column Column!	Kolumna, do której należy wartość.
id ID!	Unikalny identyfikator kolumny.
text String	Wartość kolumny w postaci tekstu. Zwraca null, jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny.
value JSON	Surowa wartość kolumny w formacie JSON.
is_leaf Boolean!	Określa, czy element nie ma podelementów. Na tablicach wielopoziomowych z funkcją agregacji wartość false oznacza, że wartość została obliczona na podstawie elementów podrzędnych, a nie ustawiona statycznie.

---

Filtrowanie

Możesz filtrować elementy według wartości statusu za pomocą obiektu items_page. Filtry obsługują wyszukiwanie według:

• identyfikatora etykiety (zalecane),
• tekstu etykiety (contains_terms),
• pustych wartości.

Operator	Wartość porównania	Opis
any_of	Tablica identyfikatorów etykiet (np. [1, 2])	Zwraca elementy, których status pasuje do dowolnego z podanych identyfikatorów etykiet. Identyfikatory możesz znaleźć, odpytując ustawienia kolumny.
not_any_of	Tablica identyfikatorów etykiet (np. [1, 2])	Pomija elementy, których status pasuje do któregokolwiek z podanych identyfikatorów etykiet.
contains_terms	Tekst etykiety (np. "Done")	Zwraca elementy, których etykieta statusu zawiera podany tekst.
is_empty	[]	Zwraca elementy z pustą (nieustawioną) wartością statusu.
is_not_empty	[]	Zwraca elementy z ustawioną wartością statusu.

Przykłady

Filtrowanie według identyfikatora etykiety

Ten przykład zwraca wszystkie elementy z etykietą statusu o identyfikatorze 1 (na domyślnych tablicach jest to zwykle „Done”).

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: [1]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on StatusValue {
            label
            index
          }
        }
      }
    }
  }
}

Filtrowanie według tekstu etykiety statusu

Ten przykład zwraca wszystkie elementy na wskazanej tablicy z etykietą „Done”.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: "Done"
            operator: contains_terms
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on StatusValue {
            label
          }
        }
      }
    }
  }
}

Filtrowanie według pustego statusu

Ten przykład zwraca wszystkie elementy na wskazanej tablicy z pustą wartością statusu.

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

---

Mutacje

Tworzenie

Wymagany zakres: boards:write

Mutacja create_status_column tworzy nową kolumnę statusu z ustawieniami o określonych typach za pomocą API. Możesz wskazać, które pola mają zostać zwrócone w odpowiedzi na mutację.

mutation {
  create_status_column(
    board_id: 1234567890
    id: "project_status"
    title: "Project Status"
    defaults: {
      labels: [
        { color: done_green, label: "Done", index: 0, is_done: true }
        { color: working_orange, label: "Working on it", index: 1 }
        { color: stuck_red, label: "Stuck", index: 2 }
        { color: bright_blue, label: "Waiting for review", index: 3 }
      ]
    }
    description: "The project's current status."
  ) {
    id
    title
    description
    settings
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Unikalny identyfikator tablicy.
id	String	Własny identyfikator kolumny. Jeśli go nie podasz, zostanie wygenerowany automatycznie.
title	String!	Tytuł kolumny.
description	String	Opis kolumny.
after_column_id	ID	Identyfikator kolumny, za którą ma zostać wstawiona nowa kolumna.
defaults CreateStatusColumnSettingsInput	Object	Konfiguracja etykiet kolumny. Zobacz pola wejściowe etykiety poniżej.
capabilities StatusColumnCapabilitiesInput	Object	Ustawienia funkcji kolumny (np. funkcji obliczania i agregacji).

Pola wejściowe etykiety (CreateStatusLabelInput)

Pole	Typ	Wymagane	Opis
label	String!	Tak	Tekst wyświetlany etykiety (maks. 30 znaków).
color	StatusColumnColors!	Tak	Kolor etykiety. Zobacz dostępne kolory.
index	Int!	Tak	Pozycja etykiety w kolejności wyświetlania (0–39).
description	String	Nie	Opcjonalny opis etykiety.
is_done	Boolean	Nie	Określa, czy etykieta oznacza stan „ukończono”. Domyślnie false.

Aktualizowanie ustawień kolumny

Wymagany zakres: boards:write

Mutacja update_status_column aktualizuje ustawienia istniejącej kolumny statusu, w tym jej tytuł, opis i konfigurację etykiet.

mutation {
  update_status_column(
    board_id: 1234567890
    id: "status"
    revision: "replace_with_current_revision"
    title: "Task Status"
    settings: {
      labels: [
        { id: 1, color: done_green, label: "Complete", index: 0, is_done: true }
        { id: 0, color: working_orange, label: "In Progress", index: 1 }
        { id: 2, color: stuck_red, label: "Blocked", index: 2 }
        { id: 7, color: bright_blue, label: "Draft", index: 3, is_deactivated: false }
      ]
    }
  ) {
    id
    title
    settings
  }
}

Argumenty

Argument	Typ	Wymagane	Opis
board_id	ID!	Tak	Unikalny identyfikator tablicy.
id	String!	Tak	Unikalny identyfikator kolumny.
revision	String!	Tak	Bieżąca wersja kolumny używana do wykrywania konfliktów.
title	String	Nie	Nowy tytuł kolumny.
description	String	Nie	Nowy opis kolumny.
width	Int	Nie	Szerokość kolumny w pikselach.
settings UpdateStatusColumnSettingsInput	Object	Nie	Zaktualizowana konfiguracja etykiet kolumny.
capabilities StatusColumnCapabilitiesInput	Object	Nie	Zaktualizowane ustawienia funkcji kolumny.

Pola wejściowe aktualizowanej etykiety (UpdateStatusLabelInput)

Pole	Typ	Wymagane	Opis
label	String!	Tak	Tekst wyświetlany etykiety (maks. 30 znaków).
color	StatusColumnColors!	Tak	Kolor etykiety.
index	Int!	Tak	Pozycja etykiety w kolejności wyświetlania (0–39).
id	Int	Nie	Unikalny identyfikator etykiety. Wymagany podczas aktualizowania istniejącej etykiety.
description	String	Nie	Opcjonalny opis etykiety.
is_deactivated	Boolean	Nie	Określa, czy etykieta jest nieaktywna (ukryta w interfejsie).
is_done	Boolean	Nie	Określa, czy etykieta oznacza stan „ukończono”.

Aktualizowanie wartości

Możesz aktualizować wartość kolumny statusu za pomocą change_simple_column_value lub change_multiple_column_values. W zależności od wybranej mutacji możesz przesłać wartości jako zwykłe ciągi znaków lub obiekty JSON.

Każda kolumna statusu może zawierać maksymalnie 40 etykiet.

Wartość kolumny możesz aktualizować za pomocą:

• wartości indeksu - są stabilne i zalecane, zwłaszcza gdy pracujesz na wielu tablicach;
• tekstu etykiety - jest czytelny, ale może powodować problemy, jeśli etykiety się zmienią.

change_simple_column_value

Przekaż indeks lub wartość etykiety w argumencie value.

Aktualizowanie według indeksu

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: "1"
  ) {
    id
    name
  }
}

Aktualizowanie według tekstu etykiety

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: "Done"
    create_labels_if_missing: true
  ) {
    id
    name
  }
}

change_multiple_column_values

Przekaż klucze index lub label jako obiekt JSON w polu column_values.

Aktualizowanie według indeksu (JSON)

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": {\"index\": 1}}"
  ) {
    id
    name
  }
}

Aktualizowanie według etykiety (JSON)

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": {\"label\": \"Done\"}}"
    create_labels_if_missing: true
  ) {
    id
    name
  }
}

Ustawianie statusu podczas tworzenia elementu

Możesz ustawić wartość statusu podczas tworzenia elementu, przekazując wartość kolumny statusu w argumencie column_values.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"status\": {\"label\": \"Working on it\"}}"
  ) {
    id
    name
  }
}

Czyszczenie

Możesz wyczyścić kolumnę statusu za pomocą change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż pusty ciąg znaków w polu value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "status"
    value: ""
  ) {
    id
    name
  }
}

change_multiple_column_values

Przekaż null lub pusty obiekt w polu column_values.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": null}"
  ) {
    id
    name
  }
}

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić etykiety, kolory i strukturę kolumny statusu, odpytaj jej ustawienia za pomocą pola settings kolumny.

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

Struktura odpowiedzi settings

Pole	Typ	Opis
labels	StatusLabel[]	Tablica obiektów etykiet reprezentujących dostępne wartości statusu.

StatusLabel

Pole	Typ	Wymagane	Opis
id	number	Tak	Unikalny identyfikator liczbowy etykiety. Tej wartości należy użyć podczas aktualizowania statusu za pomocą API (zobacz ostrzeżenie poniżej).
label	string	Tak	Tekst wyświetlany etykiety statusu (np. "Working on it", "Done", "Stuck").
color	StatusColumnColors	Tak	Wartość wyliczeniowa koloru. Zobacz dostępne kolory.
hex	string	Nie	Zastępczy kod koloru Hex (np. "#fdab3d"). Jeśli jest podany, ma pierwszeństwo przed wartością color.
index	number	Tak	Pozycja etykiety (kolejność wyświetlania) w kolumnie statusu.
description	string	Nie	Opcjonalny opis etykiety.
is_deactivated	boolean	Nie	Określa, czy etykieta jest nieaktywna (ukryta w interfejsie). Domyślnie false.
is_done	boolean	Nie	Określa, czy etykieta oznacza stan „ukończono”. Domyślnie false.

Przykładowa odpowiedź

{
  "settings": {
    "type": "status",
    "labels": [
      {
        "id": 0,
        "label": "Working on it",
        "color": "working_orange",
        "index": 0,
        "is_done": false
      },
      {
        "id": 1,
        "label": "Done",
        "color": "done_green",
        "index": 1,
        "is_done": true
      },
      {
        "id": 2,
        "label": "Stuck",
        "color": "stuck_red",
        "index": 2,
        "is_done": false
      }
    ]
  }
}

id a index - ważna różnica

Przykład

Załóżmy, że kolumna statusu zawiera następujące etykiety:

id	index (pozycja)	Etykieta
1	0	Done
0	1	Working on it
2	2	Stuck

Aby ustawić status elementu na „Done”, przekaż {"index": 1} (id etykiety, a nie jej pozycję wyświetlania):

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"status\": {\"index\": 1}}"
  ) {
    id
  }
}

---

Mapowanie indeksów i kolorów

Kolumny statusu używają indeksów do identyfikowania poszczególnych etykiet. Każdy indeks odpowiada etykiecie i kolorowi. Mapowanie można dostosować osobno dla każdej tablicy.

Poniżej znajdują się domyślne mapowania monday.com:

Indeks	Domyślna etykieta	Domyślny kolor	Kod koloru
0	(Pusta/bez etykiety)	Szary	#c4c4c4
1	Done	Zielony	#00c875
2	Working on it	Pomarańczowy	#fdab3d
3	Stuck	Czerwony	#e2445c
4	(Własna)	Niebieski	#0086c0
5	(Pusta)	Szary	#c4c4c4

Zobacz pełną listę domyślnych wartości indeksów i kolorów.

Ważne informacje

Indeksy są stabilne, ale tekst etykiety i kolory można dostosować. Oznacza to, że mapowanie poszczególnych indeksów może się różnić między tablicami.

Na przykład:

• Indeks 1 może początkowo oznaczać zieloną etykietę „Done”.
• Administrator tablicy zmienia ją na niebieską etykietę „Completed”.
• Indeks pozostaje równy 1, ale wyświetlana etykieta i kolor się zmieniają.

Nie zakładaj, że ten sam indeks oznacza tę samą etykietę lub kolor na każdej tablicy. Zawsze sprawdzaj konfigurację tablicy za pomocą następującego zapytania:

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

---

Dostępne kolory

Wartość wyliczeniowa StatusColumnColors określa 40 dostępnych kolorów etykiet statusu. Możesz odwoływać się do nich według nazwy (w mutacjach) lub identyfikatora liczbowego.

Nazwa koloru	Identyfikator liczbowy	Kod Hex
working_orange	0	fdab3d
done_green	1	00c875
stuck_red	2	e2445c
dark_blue	3	0086c0
purple	4	9d50dd
explosive	5	ff642e
grass_green	6	037f4c
bright_blue	7	579bfc
saladish	8	cab641
egg_yolk	9	ffcb00
blackish	10	333333
dark_red	11	bb3354
sofia_pink	12	ff158a
lipstick	13	ff5ac4
dark_purple	14	784bd1
bright_green	15	9cd326
chili_blue	16	66ccff
american_gray	17	808080
brown	18	7f5347
dark_orange	19	d974b0
sunset	101	ff7575
bubble	102	faa1f1
peach	103	ffadad
berry	104	e8697d
winter	105	9aadbd
river	106	68a1bd
navy	107	225091
aquamarine	108	4eccc6
indigo	109	5559df
dark_indigo	110	401694
pecan	151	563e3e
lavender	152	a25ddc
royal	153	2b76e5
steel	154	a9bee8
orchid	155	dce3ea
lilac	156	bda8f0
tan	157	a0a0a0
sky	158	a1e3f6
coffee	159	bd816e
teal	160	2da283

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny statusu 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: status
  )
}

{
  "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": {
              "type": {
                "type": "string",
                "description": "The type of managed column (status)"
              },
              "labels": {
                "type": "array",
                "maxItems": 40,
                "description": "Array of status labels",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "The unique identifier for the label"
                    },
                    "label": {
                      "type": "string",
                      "maxLength": 30,
                      "description": "The display text for the label"
                    },
                    "color": {
                      "oneOf": [
                        {
                          "type": "string",
                          "enum": [
                            "working_orange",
                            "done_green",
                            "stuck_red",
                            "..."
                          ],
                          "description": "The color name from StatusColumnColors enum"
                        },
                        {
                          "type": "integer",
                          "description": "The color value from StatusColumnColors enum"
                        }
                      ]
                    },
                    "index": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 39,
                      "description": "The display order of the label"
                    },
                    "is_done": {
                      "type": "boolean",
                      "description": "Whether the label represents a done state"
                    }
                  },
                  "required": [
                    "label",
                    "color",
                    "index"
                  ]
                }
              }
            },
            "required": [
              "labels"
            ]
          }
        }
      }
    }
  }
}

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 lub dostarczenia kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.