Labels

Overview

The Labels API is a server-side text classification endpoint that returns raw moderation labels for a piece of text. It is designed for integrations that need the classification signal on its own — without creating review-queue items, flags, actions, or webhooks.

Use it when you want to label text and decide yourself what to do with the result: filter content, route it, tag it for analytics, or feed it into your own downstream systems. For the full automated moderation workflow (review queue, actions, appeals), use the Moderation Check endpoint instead.

Storage model

Calls to the Labels API are stateless by default. The request is classified by your configured providers (see Provider Routing), the response is returned synchronously, and the content, labels, and classification are not persisted by Stream.

Optional storage is available for organizations that need to query labels historically (for analytics, trend analysis, investigations, or custom dashboards). When storage is enabled, results containing at least one label are persisted and can be queried via the queryLabelResults method. Content that returns zero labels is not stored.

Provider Routing

The classification endpoint runs different providers depending on the request. No setup is required for the default path — send text, get labels.

To customize classification (custom LLM prompts, specific blocklists, your own harm taxonomy), define a policy and pass its key as policy on the request.

Classify Content

Classifies a single piece of text and returns labels synchronously. Server-side only.

const response = await client.moderation.labels({
  content: "you are a fucking idiot",
  content_type: "message",
  category: "chat",
  content_id: "msg-123",
  user_id: "user-42",
});

response = client.moderation().labels(
    content="you are a fucking idiot",
    content_type="message",
    category="chat",
    content_id="msg-123",
    user_id="user-42",
)

response, err := client.Moderation().Labels(ctx, &getstream.LabelsRequest{
    Content:     "you are a fucking idiot",
    ContentType: getstream.PtrTo("message"),
    Category:    getstream.PtrTo("chat"),
    ContentID:   getstream.PtrTo("msg-123"),
    UserID:      getstream.PtrTo("user-42"),
})

LabelsResponse response = client.moderation()
    .labels(LabelsRequest.builder()
        .content("you are a fucking idiot")
        .contentType("message")
        .category("chat")
        .contentID("msg-123")
        .userID("user-42")
        .build())
    .execute()
    .getData();

$response = $client->moderation()->labels(new LabelsRequest(
    content: 'you are a fucking idiot',
    contentType: 'message',
    category: 'chat',
    contentID: 'msg-123',
    userID: 'user-42',
));

response = client.moderation.labels(
  GetStream::Generated::Models::LabelsRequest.new(
    content: "you are a fucking idiot",
    content_type: "message",
    category: "chat",
    content_id: "msg-123",
    user_id: "user-42",
  )
)

var response = await client.Moderation.LabelsAsync(new LabelsRequest
{
    Content = "you are a fucking idiot",
    ContentType = "message",
    Category = "chat",
    ContentID = "msg-123",
    UserID = "user-42",
});

Request Params

Response

{
  "labels": ["insult", "vulgarity"],
  "harm_type": "hateful",
  "directed_at": "user",
  "recommended_action": "keep",
  "severity": "low",
  "language": "en",
  "content_id": "msg-123",
  "masked_content": "you are a ******* *****",
  "duration": "119.85ms"
}

Error handling

• Provider errors (rate limits, upstream timeouts) surface as errors. Content is not silently returned as keep when classification fails.
• Requesting a policy that doesn't exist returns a 400 error.
• The endpoint is server-side only. Client-side tokens are rejected.

Query Stored Results

Query persisted label results with filtering, sorting, and pagination. Requires storage to be enabled on the organization — see Storage model.

const response = await client.moderation.queryLabelResults({
  filter: {
    category: "chat",
    language: "en",
    harm_type: "hateful",
    date_range: "2026-04-01_2026-04-23",
  },
  sort: [{ field: "created_at", direction: -1 }],
  limit: 25,
});

response = client.moderation().query_label_results(
    filter={
        "category": "chat",
        "language": "en",
        "harm_type": "hateful",
        "date_range": "2026-04-01_2026-04-23",
    },
    sort=[SortParamRequest(field="created_at", direction=-1)],
    limit=25,
)

response, err := client.Moderation().QueryLabelResults(ctx, &getstream.QueryLabelResultsRequest{
    Filter: map[string]any{
        "category":   "chat",
        "language":   "en",
        "harm_type":  "hateful",
        "date_range": "2026-04-01_2026-04-23",
    },
    Sort: []getstream.SortParamRequest{
        {Field: getstream.PtrTo("created_at"), Direction: getstream.PtrTo(-1)},
    },
    Limit: getstream.PtrTo(25),
})

QueryLabelResultsResponse response = client.moderation()
    .queryLabelResults(QueryLabelResultsRequest.builder()
        .filter(Map.of(
            "category", "chat",
            "language", "en",
            "harm_type", "hateful",
            "date_range", "2026-04-01_2026-04-23"
        ))
        .sort(List.of(SortParamRequest.builder().field("created_at").direction(-1).build()))
        .limit(25)
        .build())
    .execute()
    .getData();

$response = $client->moderation()->queryLabelResults(new QueryLabelResultsRequest(
    filter: [
        'category' => 'chat',
        'language' => 'en',
        'harm_type' => 'hateful',
        'date_range' => '2026-04-01_2026-04-23',
    ],
    sort: [new SortParamRequest(field: 'created_at', direction: -1)],
    limit: 25,
));

response = client.moderation.query_label_results(
  GetStream::Generated::Models::QueryLabelResultsRequest.new(
    filter: {
      category: "chat",
      language: "en",
      harm_type: "hateful",
      date_range: "2026-04-01_2026-04-23",
    },
    sort: [GetStream::Generated::Models::SortParamRequest.new(field: "created_at", direction: -1)],
    limit: 25,
  )
)

var response = await client.Moderation.QueryLabelResultsAsync(new QueryLabelResultsRequest
{
    Filter = new Dictionary<string, object>
    {
        { "category", "chat" },
        { "language", "en" },
        { "harm_type", "hateful" },
        { "date_range", "2026-04-01_2026-04-23" },
    },
    Sort = new List<SortParamRequest>
    {
        new() { Field = "created_at", Direction = -1 },
    },
    Limit = 25,
});

Available Filters

Response

{
  "label_results": [
    {
      "id": "30dff5ac-6b80-486c-9da1-fcb938849642",
      "created_at": "2026-04-16T10:30:00Z",
      "content": "you are a fucking idiot",
      "masked_content": "you are a ******* *****",
      "content_type": "message",
      "category": "chat",
      "labels": ["insult", "vulgarity"],
      "harm_type": "hateful",
      "directed_at": "user",
      "recommended_action": "keep",
      "severity": "low",
      "language": "en",
      "content_id": "msg-123",
      "user_id": "user-42"
    }
  ],
  "next": "...",
  "prev": "..."
}

Use next / prev for cursor-based pagination.

Labels vs Check

Use Labels when you want the classification result and will handle the rest yourself. Use Check when you want Stream to run the end-to-end moderation workflow.

Rate Limits

If your workload requires higher throughput, contact us to arrange a per-organization override.

Related APIs

• Moderation Check — Full moderation workflow with review queue and actions.
• Policies — Configure custom classifiers (LLM prompts, blocklists, harm taxonomies).
• AI Text (NLP) — The NLP engine used by default.
• AI Text (LLM) — LLM-based classification available via policies.