Labels

Overview

The Confident AI SDK exposes every Label method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Labels

Lists a classifier's labels one page at a time, ordered by name. This is also how you read the results of a generation run — generated suggestions arrive with status RECOMMENDED. Each label is returned as a summary row; retrieve one by id for its description and polarity. Requires the Starter plan or above.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.classifiers.list_labels(
    classifier_id="<CLASSIFIER-ID>",
    page=1,
    page_size=25,
)

For async mode, call a_list_labels and await it as shown below:

result = await client.classifiers.a_list_labels(...)

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.
`page`	`Optional[int]`	The page to return. Defaults to 1.
`page_size`	`Optional[int]`	The number of results per page, at most 100. Defaults to 25.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.classifiers.listLabels(
  "<CLASSIFIER-ID>",
  { page: 1, pageSize: 25 },
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.
`page`	`number`	The page to return. Defaults to 1.
`pageSize`	`number`	The number of results per page, at most 100. Defaults to 25.

Returns

This method returns an object of type ClassifierLabelList.

Create Label

Adds a label to a classifier and returns its id. The description is what the classifying model matches against, so write it as a clear statement of when the label applies rather than a restatement of the name. Label names are unique within a classifier. Requires the Starter plan or above.

from confident_ai import ConfidentAI
from confident_ai.classifiers import ClassifierLabelStatus
from confident_ai.classifiers import SignalPolarity

client = ConfidentAI()

result = client.classifiers.create_label(
    classifier_id="<CLASSIFIER-ID>",
    name="Positive",
    description="User expresses satisfaction, gratitude, or positive sentiment.",
    enabled=True,
    status=ClassifierLabelStatus.RECOMMENDED,
    polarity=SignalPolarity.HIGHER_IS_BETTER,
)

For async mode, call a_create_label and await it as shown below:

result = await client.classifiers.a_create_label(...)

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.
`name`	`str`	Required. The name of the label, unique within the classifier.
`description`	`str`	Required. When this label applies. It is the instruction the classifying model reads, so state the condition rather than restating the name.
`enabled`	`Optional[bool]`	Whether the label can be applied. Defaults to true.
`status`	`Optional[ClassifierLabelStatus]`	See ClassifierLabelStatus.
`polarity`	`Optional[SignalPolarity]`	See SignalPolarity.

import { ConfidentAI } from "confident-ai";
import {
  ClassifierLabelStatus,
  SignalPolarity,
} from "confident-ai/classifiers";

const client = new ConfidentAI();

const result = await client.classifiers.createLabel(
  "<CLASSIFIER-ID>",
  "Positive",
  "User expresses satisfaction, gratitude, or positive sentiment.",
  {
    enabled: true,
    status: ClassifierLabelStatus.RECOMMENDED,
    polarity: SignalPolarity.HIGHER_IS_BETTER
  },
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.
`name`	`string`	Required. The name of the label, unique within the classifier.
`description`	`string`	Required. When this label applies. It is the instruction the classifying model reads, so state the condition rather than restating the name.
`enabled`	`boolean`	Whether the label can be applied. Defaults to true.
`status`	`ClassifierLabelStatus`	See ClassifierLabelStatus.
`polarity`	`SignalPolarity`	See SignalPolarity.

Returns

This method returns an object of type ClassifierLabelRef.

Get Label

Retrieves a single label on a classifier, with the description the classifying model matches against and the polarity trend reporting uses. Requires the Starter plan or above.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.classifiers.get_label(
    classifier_id="<CLASSIFIER-ID>",
    label_id="<CLASSIFIER-LABEL-ID>",
)

For async mode, call a_get_label and await it as shown below:

result = await client.classifiers.a_get_label(...)

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier the label belongs to.
`label_id`	`str`	Required. The id of the label.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.classifiers.getLabel(
  "<CLASSIFIER-ID>",
  "<CLASSIFIER-LABEL-ID>",
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier the label belongs to.
`labelId`	`string`	Required. The id of the label.

Returns

This method returns an object of type ClassifierLabel.

Update Label

Updates a label on a classifier and returns it. Only the fields you send are changed. Promoting a generated suggestion is an update to status ACTIVE, which also enables the label. Requires the Starter plan or above.

from confident_ai import ConfidentAI
from confident_ai.classifiers import ClassifierLabelStatus
from confident_ai.classifiers import SignalPolarity

client = ConfidentAI()

result = client.classifiers.update_label(
    classifier_id="<CLASSIFIER-ID>",
    label_id="<CLASSIFIER-LABEL-ID>",
    name="Positive",
    description="User expresses satisfaction, gratitude, or positive sentiment.",
    enabled=True,
    status=ClassifierLabelStatus.RECOMMENDED,
    polarity=SignalPolarity.HIGHER_IS_BETTER,
)

For async mode, call a_update_label and await it as shown below:

result = await client.classifiers.a_update_label(...)

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier the label belongs to.
`label_id`	`str`	Required. The id of the label.
`name`	`Optional[str]`	The name of the label, unique within the classifier.
`description`	`Optional[str]`	When this label applies. It cannot be cleared.
`enabled`	`Optional[bool]`	Whether the label can be applied. Defaults to true.
`status`	`Optional[ClassifierLabelStatus]`	See ClassifierLabelStatus.
`polarity`	`Optional[SignalPolarity]`	See SignalPolarity.

import { ConfidentAI } from "confident-ai";
import {
  ClassifierLabelStatus,
  SignalPolarity,
} from "confident-ai/classifiers";

const client = new ConfidentAI();

const result = await client.classifiers.updateLabel(
  "<CLASSIFIER-ID>",
  "<CLASSIFIER-LABEL-ID>",
  {
    name: "Positive",
    description: "User expresses satisfaction, gratitude, or positive sentiment.",
    enabled: true,
    status: ClassifierLabelStatus.RECOMMENDED,
    polarity: SignalPolarity.HIGHER_IS_BETTER
  },
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier the label belongs to.
`labelId`	`string`	Required. The id of the label.
`name`	`string`	The name of the label, unique within the classifier.
`description`	`string`	When this label applies. It cannot be cleared.
`enabled`	`boolean`	Whether the label can be applied. Defaults to true.
`status`	`ClassifierLabelStatus`	See ClassifierLabelStatus.
`polarity`	`SignalPolarity`	See SignalPolarity.

Returns

This method returns an object of type ClassifierLabel.

Delete Label

Permanently deletes a label from a classifier and returns its id. Classifications already applied with it are not removed. This action cannot be undone. Requires the Starter plan or above.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.classifiers.delete_label(
    classifier_id="<CLASSIFIER-ID>",
    label_id="<CLASSIFIER-LABEL-ID>",
)

For async mode, call a_delete_label and await it as shown below:

result = await client.classifiers.a_delete_label(...)

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier the label belongs to.
`label_id`	`str`	Required. The id of the label.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.classifiers.deleteLabel(
  "<CLASSIFIER-ID>",
  "<CLASSIFIER-LABEL-ID>",
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier the label belongs to.
`labelId`	`string`	Required. The id of the label.

Returns

This method returns an object of type ClassifierLabelRef.

Types

ClassifierLabel

One label a classifier can apply to what it classifies.

class ClassifierLabel:
    id: str
    name: str
    description: str
    enabled: bool
    status: ClassifierLabelStatus
    polarity: SignalPolarity

idstrRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

namestrRequired

The name of the label, unique within the classifier.

Example: "Positive"

descriptionstrRequired

When this label applies. This is the instruction the classifying model reads, so it states the condition rather than restating the name.

Example: "User expresses satisfaction, gratitude, or positive sentiment."

enabledboolRequired

Whether the label can be applied.

Example: true

statusClassifierLabelStatusRequired

See ClassifierLabelStatus.

polaritySignalPolarityRequired

See SignalPolarity.

interface ClassifierLabel {
  id: string;
  name: string;
  description: string;
  enabled: boolean;
  status: ClassifierLabelStatus;
  polarity: SignalPolarity;
}

idstringRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

namestringRequired

The name of the label, unique within the classifier.

Example: "Positive"

descriptionstringRequired

When this label applies. This is the instruction the classifying model reads, so it states the condition rather than restating the name.

Example: "User expresses satisfaction, gratitude, or positive sentiment."

enabledbooleanRequired

Whether the label can be applied.

Example: true

statusClassifierLabelStatusRequired

See ClassifierLabelStatus.

polaritySignalPolarityRequired

See SignalPolarity.

ClassifierLabelList

One page of labels, with the total across all pages.

class ClassifierLabelList:
    labels: List[ClassifierLabelSummary]
    total_labels: int = Field(alias="totalLabels")
    page: int
    page_size: int = Field(alias="pageSize")

labelsList[ClassifierLabelSummary]Required

The labels for the current page, ordered by name.

See ClassifierLabelSummary.

total_labelsintRequired

The total number of labels on this classifier across all pages.

Example: 3

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of labels per page.

Example: 25

interface ClassifierLabelList {
  labels: ClassifierLabelSummary[];
  totalLabels: number;
  page: number;
  pageSize: number;
}

labelsClassifierLabelSummary[]Required

The labels for the current page, ordered by name.

See ClassifierLabelSummary.

totalLabelsnumberRequired

The total number of labels on this classifier across all pages.

Example: 3

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of labels per page.

Example: 25

ClassifierLabelRef

A reference to a classifier label by its id.

class ClassifierLabelRef:
    id: str

idstrRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

interface ClassifierLabelRef {
  id: string;
}

idstringRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

ClassifierLabelStatus

ACTIVE labels are in use; RECOMMENDED ones are generated suggestions awaiting review.

class ClassifierLabelStatus(Enum):
    RECOMMENDED = "RECOMMENDED"
    ACTIVE = "ACTIVE"

enum ClassifierLabelStatus {
  RECOMMENDED = "RECOMMENDED",
  ACTIVE = "ACTIVE",
}

RECOMMENDED · ACTIVE

ClassifierLabelSummary

A label as it appears in a list: enough to triage a generated suggestion, without its description or polarity.

class ClassifierLabelSummary:
    id: str
    name: str
    enabled: bool
    status: ClassifierLabelStatus

idstrRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

namestrRequired

The name of the label.

Example: "Positive"

enabledboolRequired

Whether the label can be applied.

Example: true

statusClassifierLabelStatusRequired

See ClassifierLabelStatus.

interface ClassifierLabelSummary {
  id: string;
  name: string;
  enabled: boolean;
  status: ClassifierLabelStatus;
}

idstringRequired

The id of the label, generated by Confident AI.

Example: "<CLASSIFIER-LABEL-ID>"

namestringRequired

The name of the label.

Example: "Positive"

enabledbooleanRequired

Whether the label can be applied.

Example: true

statusClassifierLabelStatusRequired

See ClassifierLabelStatus.

SignalPolarity

Whether more of a signal is good, bad, or neither, for trend reporting.

class SignalPolarity(Enum):
    HIGHER_IS_BETTER = "HIGHER_IS_BETTER"
    LOWER_IS_BETTER = "LOWER_IS_BETTER"
    NEUTRAL = "NEUTRAL"

enum SignalPolarity {
  HIGHER_IS_BETTER = "HIGHER_IS_BETTER",
  LOWER_IS_BETTER = "LOWER_IS_BETTER",
  NEUTRAL = "NEUTRAL",
}

HIGHER_IS_BETTER · LOWER_IS_BETTER · NEUTRAL

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI