Skip to main content
This guide walks through building a Smart Category end to end. For what Smart Categories are and how they’re used across the platform, start with Smart Categories.

​
Before you start

Decide what question you’re asking. The best categories answer one specific question with a small set of mutually exclusive answers. If you can’t state the question in a sentence, the prompt will be muddy and so will the results.

​
1. Open Smart Categories

Navigate to Settings → Enrichments → Smart Categories, then click Create New. You’ll be offered two paths.

​
Create from template

Four ready-made starting points:
TemplateWhat it does
FavorabilityAnalyzes how favorably your brand, product, or organization is portrayed based on tone, framing, and context
Relevance DetectionDetermines whether mentions are truly relevant to your organization or just noise
Violent Rhetoric DetectionIdentifies mentions containing violent rhetoric or threatening language
Political Leaning DetectionIdentifies the political leaning or bias expressed in mentions
Templates are fully editable once loaded. Most teams start with Favorability and adapt it rather than writing one from scratch.

​
Create from scratch

Build your own. Use this whenever the question you’re asking is specific to your organization, which, for the categories that end up mattering most, it usually is.

​
2. Configure the category

How the category appears in filters, charts, and reports. Be specific: accounts accumulate a lot of these, and Nvidia Risk is findable six months later in a way that Risk is not.
Which workspaces the category runs against. Select at least one. You can apply a single category to several workspaces, which is useful for a standard you want applied consistently across brands, regions, or clients.
The labels the AI chooses from. At least two required.Keep the set small and mutually exclusive. Four to six options is a good target; beyond that, the boundaries between labels get blurry and classification gets less consistent.Always include an escape hatch like Not Applicable. Without one, the AI has nowhere to put mentions that genuinely don’t fit, so it will force them into your real categories and quietly corrupt your numbers.
The instructions the AI follows when deciding between your options. Generate Prompt will draft one from your name and response options, a reasonable starting point, but expect to edit it.
What content gets analyzed:
  • Mention Data: headline and body text (recommended, on by default)
  • Author Data: profile info, follower counts, publisher details; useful for credibility or influence-based classification
  • Mention Image: the primary image, for detecting logos, screenshots, or visual narratives
  • Mention Video: the first 30 seconds of video, for visual branding and spoken claims
More data improves flexibility but can decrease quality. Only enable what your prompt actually reasons about. If your prompt never references the author, turning on Author Data adds noise, not accuracy.For a deeper treatment of the non-text datasets, see Author and Image Smart Categories.

​
3. Write the prompt

A one-line prompt produces inconsistent results across thousands of mentions, because the AI has to invent the boundary between your labels on every single call. The prompts that hold up at scale read like a decision procedure, not a request.

​
Anatomy of a strong prompt

  1. Role and goal: what the model is doing, and for whom
  2. Available inputs: what data it should reason over
  3. The categories: restated explicitly
  4. An ordered sequence of tests, each ending in a decision and a STOP
  5. A relevance gate first, so off-topic content is eliminated before anything else is evaluated
  6. Explicit disqualifiers: the near-misses you don’t want captured
  7. A fallback for anything that doesn’t clearly land
  8. A strict output instruction: exactly one label, from the list
The ordering matters as much as the content. Putting the relevance gate first, and making each step terminal, is what stops the model from reasoning its way into your highest-severity bucket on a tangential mention.

​
Worked example: a risk classifier

A production-grade prompt for classifying corporate risk. Note how much of it is devoted to narrowing: the disqualifiers and the attribution test do more work than the category definitions.
Adding two or three example posts to your prompt, one for each borderline case, measurably improves consistency. Show the model the edge cases you argued about internally.
For a library of shorter prompts covering favorability, adoption trends, threat detection, ideological lean, and mention type, see the Smart Categories Workflow Guide.

​
4. Run a preview

Run Preview classifies a sample of real mentions from your workspace and shows the results in the right-hand pane. Use it properly, it’s the difference between a category you trust and one you quietly stop looking at. What to check:
  • Read the mentions labeled with your most severe option. If Critical is catching things you’d call routine, your thresholds are too loose.
  • Read the Not Applicable pile. If real, relevant content is landing there, your relevance gate is too strict or your categories don’t cover the ground.
  • Look for a single dominant label. If nearly everything lands in one bucket, the category isn’t discriminating and won’t tell you anything.
  • Iterate here, not in production. Adjust the prompt, re-run, re-read. Two or three rounds is normal.

​
5. Create and backfill

Create & Backfill saves the category and applies it to your existing workspace mentions as well as new ones going forward. That means you get trendable history immediately rather than waiting for data to accumulate.
Allow a short while for results to populate across your dashboard. Backfilling a large workspace takes longer than classifying new mentions going forward. If your smart category is not appearing in your workspace after an hour, reach out to the PeakMetrics team.
Once it’s live, find your category in the workspace dashboard charts and in Filters → Smart Categories.

​
Editing an existing category

Open any category from the Smart Categories list to change its name, workspaces, response options, prompt, or datasets. Re-run the preview after any change, then Save Changes.
Changing a prompt or response options changes what your historical data means. A mention labeled Elevated under the old definition sits alongside mentions labeled under the new one, and any trend spanning the change becomes hard to interpret. For substantial revisions, consider creating a new category instead so your existing time series stays clean, allowance permitting.

​
Troubleshooting

Usually your workspace query is broader than your category’s relevance gate. Read the Not Applicable mentions directly. If they’re genuinely off-topic, the category is working and the query needs tightening. If they’re relevant, loosen Step 1 of your prompt.
The prompt isn’t giving the model enough to discriminate on. Add explicit tests and thresholds that distinguish adjacent options, and consider whether two of your labels are actually the same thing.
Typically means the boundary between two options is underspecified. Add disqualifiers and a couple of worked examples to the prompt.
Confirm Mention Image is toggled on under Datasets Included, and remember that mentions without images will behave differently. See Author and Image Smart Categories.

Smart Categories

What they are, where they appear, and how teams use them.

Smart Categories Workflow Guide

A library of ready-to-deploy prompts across common use cases.

Author and Image Smart Categories

Classifying on visual content and author-level signals.

Exporting Data

Taking category values into your own analysis.
Need help building one? The PeakMetrics Insights Team runs working sessions to co-design categories and test prompts, email support@peakmetrics.com.