---
title: "Labels and automations"
description: "Put your own labels on mentions, change many at once, and label new mentions automatically as they arrive."
canonical: https://docs.mentio.dev/guides/labels
markdown: https://docs.mentio.dev/guides/labels.mdx
---

# Labels and automations

Put your own labels on mentions, change many at once, and label new mentions automatically as they arrive.

A label is your own word on one mention, like `hot-lead`, `replied` or `client-acme`. Use labels to run a workflow on top of the feed: what is new, what you answered, which client it belongs to.

## Labels and tags [#labels-and-tags]

* **Labels** are on a mention. Each mention carries its own, at most 20.
* **Tags** are on a person, in [People](/guides/people), and every mention by that person shows them.

Labels are exact and case-sensitive: `Hot` and `hot` are two labels.

## Label one mention [#label-one-mention]

`labels` on `PATCH /v1/mentions/{id}` replaces the mention's whole list. `[]` removes every label.

```bash
curl -X PATCH https://api.mentio.dev/v1/mentions/mm_7f3a... \
  -H "Authorization: Bearer $MENTIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["hot-lead", "client-acme"] }'
```

## Change many mentions at once [#change-many-mentions-at-once]

`POST /v1/mentions/batch` applies one change to up to 100 mentions: a page of the list.

| Field          | What it does                                  |
| -------------- | --------------------------------------------- |
| `status`       | `done`, `ignored`, or `open` to put them back |
| `assigneeId`   | A workspace member, or `null` to unassign     |
| `addLabels`    | Labels to add, never past 20 on a mention     |
| `removeLabels` | Labels to remove                              |

All of it lands, or none of it. Ids the workspace has no mention by come back in `notFound`, and the rest still change.

A mention still being classified takes the labels and the assignee but keeps its status, and comes back in `pending`. Removals run before additions, so moving a mention from `new` to `replied` is one call.

```bash
curl -X POST https://api.mentio.dev/v1/mentions/batch \
  -H "Authorization: Bearer $MENTIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["mm_7f3a...", "mm_8a1b..."],
    "update": { "status": "done", "removeLabels": ["new"], "addLabels": ["replied"] }
  }'
```

## Filter by label [#filter-by-label]

`labels` keeps mentions carrying any of the labels; `notLabels` drops them. Both work on the list, the exports, [views](/guides/views) and [alert rules](/alerts).

```bash
curl "https://api.mentio.dev/v1/mentions?labels=hot-lead&notLabels=replied" \
  -H "Authorization: Bearer $MENTIO_API_KEY"
```

`GET /v1/labels` lists the workspace's labels with how many mentions carry each, a page at a time.

## Label new mentions automatically [#label-new-mentions-automatically]

An automation is a filter plus actions. Its filter takes the fields of a view. Its actions add labels, assign a member (`assigneeId`, a user id from `GET /v1/members`), or both.

It acts on every new mention the filter selects, as soon as the mention is scored. That is before delivery, so an alert rule on `labels` already sees what it labelled.

```bash
curl -X POST https://api.mentio.dev/v1/automations \
  -H "Authorization: Bearer $MENTIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LinkedIn leads",
    "filter": { "platforms": ["linkedin"], "intents": ["buy_intent"] },
    "actions": { "addLabels": ["hot-lead"] }
  }'
```

Then route them with an alert rule whose filter is `{ "labels": ["hot-lead"] }`. A rule sees a mention's labels once, when it is delivered right after scoring: an automation's labels, or labels added before then. A label added after delivery sends nothing.

## How automations run [#how-automations-run]

* They run oldest first. A later automation sees the labels an earlier one added.
* An assignee is set only when nobody is assigned. A member who left the workspace is skipped.
* A workspace holds at most 25. Pause one with `enabled: false`.
* Mentions that already exist, and the 30-day look-back of a new keyword, are not touched. Label those with the batch call.
* Deleting an automation keeps the labels it added.

When a keyword an automation names is deleted, the automation is paused rather than widened to every mention.

## Related [#related]

* [Update many mentions](/api/mentions/update-mentions): the batch endpoint.
* [Create an automation](/api/automations/create-automation): the endpoint reference.
* [Views](/guides/views): the filter vocabulary.
* [Alerts](/alerts): send labelled mentions to a channel.