Classifiers

Every Classifiers method in the Confident AI Python and TypeScript SDKs.

Overview

The Confident AI SDK exposes every Classifier 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 Classifiers

Lists the classifiers in your Confident AI project one page at a time, ordered by name. Each is returned as a summary row — enough to pick one; retrieve a classifier by id for its filters, generation config, and labels. Requires the Starter plan or above.

from confident_ai import ConfidentAI
from confident_ai.classifiers import ClassifierDataModel

client = ConfidentAI()

result = client.classifiers.list(
    page=1,
    page_size=25,
    data_model=ClassifierDataModel.TRACE,
)

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

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

Parameters

Parameter	Type	Description
`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.
`data_model`	`Optional[ClassifierDataModel]`	See ClassifierDataModel.

import { ConfidentAI } from "confident-ai";
import { ClassifierDataModel } from "confident-ai/classifiers";

const client = new ConfidentAI();

const result = await client.classifiers.list(
  { page: 1, pageSize: 25, dataModel: ClassifierDataModel.TRACE },
);

Parameters

Parameter	Type	Description
`page`	`number`	The page to return. Defaults to 1.
`pageSize`	`number`	The number of results per page, at most 100. Defaults to 25.
`dataModel`	`ClassifierDataModel`	See ClassifierDataModel.

Returns

This method returns an object of type ClassifierList.

Create Classifier

Creates a classifier that tags incoming traces or threads with labels, and returns its id. Sending a preset seeds it with a description, a generation config, and a starting set of labels; any field you send explicitly overrides what the preset would have set. Requires the Starter plan or above.

from confident_ai import ConfidentAI
from confident_ai.classifiers import ClassifierAutoGenerationConfig
from confident_ai.classifiers import ClassifierDataModel
from confident_ai.classifiers import ClassifierPreset

client = ConfidentAI()

result = client.classifiers.create(
    name="Sentiment",
    data_model=ClassifierDataModel.TRACE,
    preset=ClassifierPreset.CUSTOM,
    description="Analyzes the emotional tone of user interactions.",
    enabled=True,
    auto_classify=True,
    filters={
        "operator": "AND",
        "groups": [
            {
                "operator": "AND",
                "filters": [
                    {
                        "category": "Trace Name",
                        "condition": "Is",
                        "value": "checkout"
                    }
                ]
            }
        ]
    },
    auto_generation_config=ClassifierAutoGenerationConfig(
        summary_prompt="Analyze the user's input to determine the emotional tone they express.",
        n_clusters=3,
        sample_size=200
    ),
)

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

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

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the classifier, unique per data model within the project.
`data_model`	`ClassifierDataModel`	Required. See ClassifierDataModel.
`preset`	`Optional[ClassifierPreset]`	See ClassifierPreset.
`description`	`Optional[str]`	What this classifier is for. Send null to clear it.
`enabled`	`Optional[bool]`	Whether the classifier runs at all. Defaults to true.
`auto_classify`	`Optional[bool]`	Whether incoming items are classified automatically as they arrive. Defaults to true.
`filters`	`Optional[FilterSet]`	Narrows which traces or threads the classifier runs on, so it can watch one route rather than the whole project. Only the groups are stored, so the set's top-level operator is dropped and the groups are combined by the platform. Send null to clear the filters and classify everything of this data model. See FilterSet.
`auto_generation_config`	`Optional[ClassifierAutoGenerationConfig]`	How a generation run samples and clusters your traffic to discover labels. Send null to clear it. See ClassifierAutoGenerationConfig.

import { ConfidentAI } from "confident-ai";
import {
  ClassifierDataModel,
  ClassifierPreset,
} from "confident-ai/classifiers";

const client = new ConfidentAI();

const result = await client.classifiers.create(
  "Sentiment",
  ClassifierDataModel.TRACE,
  {
    preset: ClassifierPreset.CUSTOM,
    description: "Analyzes the emotional tone of user interactions.",
    enabled: true,
    autoClassify: true,
    filters: {
      operator: "AND",
      groups: [
        {
          operator: "AND",
          filters: [{ category: "Trace Name", condition: "Is", value: "checkout" }]
        }
      ]
    },
    autoGenerationConfig: {
      summaryPrompt: "Analyze the user's input to determine the emotional tone they express.",
      nClusters: 3,
      sampleSize: 200
    }
  },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the classifier, unique per data model within the project.
`dataModel`	`ClassifierDataModel`	Required. See ClassifierDataModel.
`preset`	`ClassifierPreset`	See ClassifierPreset.
`description`	`string \| null`	What this classifier is for. Send null to clear it.
`enabled`	`boolean`	Whether the classifier runs at all. Defaults to true.
`autoClassify`	`boolean`	Whether incoming items are classified automatically as they arrive. Defaults to true.
`filters`	`FilterSet \| null`	Narrows which traces or threads the classifier runs on, so it can watch one route rather than the whole project. Only the groups are stored, so the set's top-level operator is dropped and the groups are combined by the platform. Send null to clear the filters and classify everything of this data model. See FilterSet.
`autoGenerationConfig`	`ClassifierAutoGenerationConfig \| null`	How a generation run samples and clusters your traffic to discover labels. Send null to clear it. See ClassifierAutoGenerationConfig.

Returns

This method returns an object of type ClassifierRef.

Get Classifier

Retrieves a classifier by id, with the filters that scope what it runs on, its generation config, and every label it can apply. Requires the Starter plan or above.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.classifiers.get(classifier_id="<CLASSIFIER-ID>")

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

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

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

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

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.

Returns

This method returns an object of type Classifier.

Update Classifier

Updates a classifier and returns it. Only the fields you send are changed: omitting a field leaves it untouched, and sending null clears it. dataModel cannot be changed after creation and a preset can only be applied when creating one; labels are managed through their own endpoints. Requires the Starter plan or above.

from confident_ai import ConfidentAI
from confident_ai.classifiers import ClassifierAutoGenerationConfig

client = ConfidentAI()

result = client.classifiers.update(
    classifier_id="<CLASSIFIER-ID>",
    name="Sentiment",
    description="Analyzes the emotional tone of user interactions.",
    enabled=True,
    auto_classify=True,
    filters={
        "operator": "AND",
        "groups": [
            {
                "operator": "AND",
                "filters": [
                    {
                        "category": "Trace Name",
                        "condition": "Is",
                        "value": "checkout"
                    }
                ]
            }
        ]
    },
    auto_generation_config=ClassifierAutoGenerationConfig(
        summary_prompt="Analyze the user's input to determine the emotional tone they express.",
        n_clusters=3,
        sample_size=200
    ),
)

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

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

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.
`name`	`Optional[str]`	The name of the classifier, unique per data model within the project.
`description`	`Optional[str]`	What this classifier is for. Send null to clear it.
`enabled`	`Optional[bool]`	Whether the classifier runs at all. Defaults to true.
`auto_classify`	`Optional[bool]`	Whether incoming items are classified automatically as they arrive. Defaults to true.
`filters`	`Optional[FilterSet]`	Narrows which traces or threads the classifier runs on, so it can watch one route rather than the whole project. Only the groups are stored, so the set's top-level operator is dropped and the groups are combined by the platform. Send null to clear the filters and classify everything of this data model. See FilterSet.
`auto_generation_config`	`Optional[ClassifierAutoGenerationConfig]`	How a generation run samples and clusters your traffic to discover labels. Send null to clear it. See ClassifierAutoGenerationConfig.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.classifiers.update(
  "<CLASSIFIER-ID>",
  {
    name: "Sentiment",
    description: "Analyzes the emotional tone of user interactions.",
    enabled: true,
    autoClassify: true,
    filters: {
      operator: "AND",
      groups: [
        {
          operator: "AND",
          filters: [{ category: "Trace Name", condition: "Is", value: "checkout" }]
        }
      ]
    },
    autoGenerationConfig: {
      summaryPrompt: "Analyze the user's input to determine the emotional tone they express.",
      nClusters: 3,
      sampleSize: 200
    }
  },
);

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.
`name`	`string`	The name of the classifier, unique per data model within the project.
`description`	`string \| null`	What this classifier is for. Send null to clear it.
`enabled`	`boolean`	Whether the classifier runs at all. Defaults to true.
`autoClassify`	`boolean`	Whether incoming items are classified automatically as they arrive. Defaults to true.
`filters`	`FilterSet \| null`	Narrows which traces or threads the classifier runs on, so it can watch one route rather than the whole project. Only the groups are stored, so the set's top-level operator is dropped and the groups are combined by the platform. Send null to clear the filters and classify everything of this data model. See FilterSet.
`autoGenerationConfig`	`ClassifierAutoGenerationConfig \| null`	How a generation run samples and clusters your traffic to discover labels. Send null to clear it. See ClassifierAutoGenerationConfig.

Returns

This method returns an object of type Classifier.

Delete Classifier

Permanently deletes a classifier and all of its labels, and returns its id. Classifications already applied to traces or threads 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(classifier_id="<CLASSIFIER-ID>")

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

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

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

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

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.

Returns

This method returns an object of type ClassifierRef.

Generate Labels

Discovers labels for a classifier from your project's real traffic: it samples recent traces or threads, clusters them with the classifier's autoGenerationConfig, and writes the themes it finds back as RECOMMENDED labels for a human to review. The run is asynchronous, so poll the labels endpoint for results. Each run first deletes every existing RECOMMENDED label, while labels already promoted to ACTIVE are kept and passed to the generator so it does not propose them again. autoGenerationConfig must already have summaryPrompt and nClusters set. Reading traffic and running the model consumes usage. Requires the Starter plan or above.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.classifiers.generate_labels(classifier_id="<CLASSIFIER-ID>")

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

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

Parameters

Parameter	Type	Description
`classifier_id`	`str`	Required. The id of the classifier.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

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

Parameters

Parameter	Type	Description
`classifierId`	`string`	Required. The id of the classifier.

Returns

This method returns an object of type ClassifierLabelGeneration.

Types

Classifier

A classifier: what it runs on, how it discovers labels, and the labels it can apply.

class Classifier:
    id: str
    name: str
    description: Optional[str]
    enabled: bool
    auto_classify: bool = Field(alias="autoClassify")
    data_model: ClassifierDataModel = Field(alias="dataModel")
    filters: FilterSet
    auto_generation_config: Optional[ClassifierAutoGenerationConfig] = Field(alias="autoGenerationConfig")
    labels: List[ClassifierLabel]

idstrRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

namestrRequired

The name of the classifier.

Example: "Sentiment"

descriptionOptional[str]Required

What this classifier is for, or null when it has no description.

Example: "Analyzes the emotional tone of user interactions."

enabledboolRequired

Whether the classifier runs at all.

Example: true

auto_classifyboolRequired

Whether incoming items are classified automatically as they arrive.

Example: true

data_modelClassifierDataModelRequired

See ClassifierDataModel.

filtersFilterSetRequired

See FilterSet.

auto_generation_configOptional[ClassifierAutoGenerationConfig]Required

How a generation run samples and clusters your traffic, or null when the classifier has no generation config.

See ClassifierAutoGenerationConfig.

labelsList[ClassifierLabel]Required

The labels this classifier can apply.

See ClassifierLabel.

interface Classifier {
  id: string;
  name: string;
  description: string | null;
  enabled: boolean;
  autoClassify: boolean;
  dataModel: ClassifierDataModel;
  filters: FilterSet;
  autoGenerationConfig: ClassifierAutoGenerationConfig | null;
  labels: ClassifierLabel[];
}

idstringRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

namestringRequired

The name of the classifier.

Example: "Sentiment"

descriptionstring | nullRequired

What this classifier is for, or null when it has no description.

Example: "Analyzes the emotional tone of user interactions."

enabledbooleanRequired

Whether the classifier runs at all.

Example: true

autoClassifybooleanRequired

Whether incoming items are classified automatically as they arrive.

Example: true

dataModelClassifierDataModelRequired

See ClassifierDataModel.

filtersFilterSetRequired

See FilterSet.

autoGenerationConfigClassifierAutoGenerationConfig | nullRequired

How a generation run samples and clusters your traffic, or null when the classifier has no generation config.

See ClassifierAutoGenerationConfig.

labelsClassifierLabel[]Required

The labels this classifier can apply.

See ClassifierLabel.

ClassifierAutoGenerationConfig

How a generation run samples and clusters your traffic. Both summaryPrompt and nClusters must be set before the generate endpoint will run.

class ClassifierAutoGenerationConfig:
    summary_prompt: str = Field(alias="summaryPrompt")
    n_clusters: int = Field(alias="nClusters")
    sample_size: Optional[int] = Field(default=None, alias="sampleSize")

summary_promptstrRequired

What the model should look for when clustering sampled traffic into themes.

Example: "Analyze the user's input to determine the emotional tone they express."

n_clustersintRequired

Roughly how many themes to cluster the sample into.

Example: 3

sample_sizeOptional[int]

How many traces or threads to sample. Defaults to 200.

Example: 200

interface ClassifierAutoGenerationConfig {
  summaryPrompt: string;
  nClusters: number;
  sampleSize?: number;
}

summaryPromptstringRequired

What the model should look for when clustering sampled traffic into themes.

Example: "Analyze the user's input to determine the emotional tone they express."

nClustersnumberRequired

Roughly how many themes to cluster the sample into.

Example: 3

sampleSizenumber

How many traces or threads to sample. Defaults to 200.

Example: 200

ClassifierDataModel

What kind of production item a classifier labels: TRACE labels individual traces, THREAD labels whole conversations. It is fixed when the classifier is created.

class ClassifierDataModel(Enum):
    TRACE = "TRACE"
    THREAD = "THREAD"

enum ClassifierDataModel {
  TRACE = "TRACE",
  THREAD = "THREAD",
}

TRACE · THREAD

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.

ClassifierLabelGeneration

The outcome of dispatching a label generation run. The run itself is asynchronous and returns no handle, so poll the labels endpoint for its results.

class ClassifierLabelGeneration:
    classifier_id: str = Field(alias="classifierId")
    started: bool
    message: str

classifier_idstrRequired

The classifier labels were generated for.

Example: "<CLASSIFIER-ID>"

startedboolRequired

Whether a generation run was dispatched. False means there was too little traffic to sample, or sampling was briefly unavailable — it is an outcome, not an error.

Example: true

messagestrRequired

A human-readable explanation of the outcome.

Example: "Label generation started. Generated labels appear with status RECOMMENDED when the run completes."

interface ClassifierLabelGeneration {
  classifierId: string;
  started: boolean;
  message: string;
}

classifierIdstringRequired

The classifier labels were generated for.

Example: "<CLASSIFIER-ID>"

startedbooleanRequired

Whether a generation run was dispatched. False means there was too little traffic to sample, or sampling was briefly unavailable — it is an outcome, not an error.

Example: true

messagestringRequired

A human-readable explanation of the outcome.

Example: "Label generation started. Generated labels appear with status RECOMMENDED when the run completes."

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

ClassifierList

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

class ClassifierList:
    classifiers: List[ClassifierSummary]
    total_classifiers: int = Field(alias="totalClassifiers")
    page: int
    page_size: int = Field(alias="pageSize")

classifiersList[ClassifierSummary]Required

The classifiers for the current page, ordered by name.

See ClassifierSummary.

total_classifiersintRequired

The total number of classifiers matching the query across all pages.

Example: 3

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of classifiers per page.

Example: 25

interface ClassifierList {
  classifiers: ClassifierSummary[];
  totalClassifiers: number;
  page: number;
  pageSize: number;
}

classifiersClassifierSummary[]Required

The classifiers for the current page, ordered by name.

See ClassifierSummary.

totalClassifiersnumberRequired

The total number of classifiers matching the query across all pages.

Example: 3

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of classifiers per page.

Example: 25

ClassifierPreset

A Confident AI template to seed a classifier from. SENTIMENT arrives with its labels ready; TOPICS, USE_CASES and ISSUES ship with none and expect a generation run next. CUSTOM seeds nothing.

class ClassifierPreset(Enum):
    CUSTOM = "CUSTOM"
    SENTIMENT = "SENTIMENT"
    TOPICS = "TOPICS"
    USE_CASES = "USE_CASES"
    ISSUES = "ISSUES"

enum ClassifierPreset {
  CUSTOM = "CUSTOM",
  SENTIMENT = "SENTIMENT",
  TOPICS = "TOPICS",
  USE_CASES = "USE_CASES",
  ISSUES = "ISSUES",
}

CUSTOM · SENTIMENT · TOPICS · USE_CASES · ISSUES

ClassifierRef

A reference to a classifier by its id.

class ClassifierRef:
    id: str

idstrRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

interface ClassifierRef {
  id: string;
}

idstringRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

ClassifierSummary

A classifier as it appears in a list: enough to pick one, without its filters, generation config, or labels.

class ClassifierSummary:
    id: str
    name: str
    enabled: bool
    data_model: ClassifierDataModel = Field(alias="dataModel")

idstrRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

namestrRequired

The name of the classifier.

Example: "Sentiment"

enabledboolRequired

Whether the classifier runs at all.

Example: true

data_modelClassifierDataModelRequired

See ClassifierDataModel.

interface ClassifierSummary {
  id: string;
  name: string;
  enabled: boolean;
  dataModel: ClassifierDataModel;
}

idstringRequired

The id of the classifier, generated by Confident AI.

Example: "<CLASSIFIER-ID>"

namestringRequired

The name of the classifier.

Example: "Sentiment"

enabledbooleanRequired

Whether the classifier runs at all.

Example: true

dataModelClassifierDataModelRequired

See ClassifierDataModel.

FilterSet

A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.

class FilterSet:
    operator: Literal["AND", "OR"]
    groups: List[FilterSetGroup]

operatorLiteral["AND", "OR"]Required

groupsList[FilterSetGroup]Required

interface FilterSet {
  operator: "AND" | "OR";
  groups: FilterSetGroup[];
}

operator"AND" | "OR"Required

groupsFilterSetGroup[]Required

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