---
title: Resolve tags and entities
category: find
summary: Turn names of people, companies, places and topics into the canonical tags Synorb filters on, and use them without broadening or guessing.
order: 8
updated: 2026-10-07
next: manifests-filter-cookbook
related: manifests-filter-cookbook, build-and-save-a-beacon
reference: /docs/api, /openapi.json
---

A **Tag** is a canonical thing: a person, an organization, a place, a topic, a data series or a resource such as a model or an API. Every Manifest has Tags. Use Tags to ask for content **about** something, no matter who published it. If you resolve a name to the right Tag, the answer is exact. If you guess, the answer can sound right and be wrong.

## When to use this

Use it whenever your user names an entity or topic and you want Manifests about it: "everything on the Federal Reserve", "anything mentioning Marc Melitz", "monetary policy this month". Use it also when you save a Beacon with `topic_filters`, which require real Tags.

## Smallest working call

Look the name up. This is free:

```bash
curl -sS "https://api.synorb.com/ontology/tags?search=Federal%20Reserve&type=organization&page_size=5" \
  -H "Authorization: Bearer $SYNORB_KEY"
```

Over MCP you usually skip the lookup. Pass the name to `synorb-manifests`. The server resolves aliases for you. Count first, and the call costs nothing:

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "tag_names": ["Federal Reserve"], "tag_type": "organization", "days": 14, "mode": "count"}
```

## What you get back

`GET /ontology/tags` returns `data.tags[]`. Each entry has the canonical name and its type:

```json response
{
  "data": {
    "tags": [
      {"tag_id": "...", "canonical_name": "Federal Reserve", "tag_type": "organization", "aliases": ["the Fed"]}
    ],
    "pagination": {"page_num": 0, "page_size": 5, "next": null, "prev": null}
  }
}
```

Copy `tag_id` and `tag_type`, and use `canonical_name` as the `tag_name`. Do not guess any of the three.

### The six Tag types

`person`, `organization`, `place`, `topic`, `data` and `resource`. A `resource` is a named addressable thing: an API endpoint, a model SKU, an SDK package. Pin a lookup to one type with `type` on the lookup, or `tag_type` on a pull. On a pull, `org` is an alias of `organization`. The Tag lookup does not accept `org`.

Each type has **subtypes**. A subtype is a second facet. Ask for `tag_type: "organization"` together with `subtype: "central_bank"`. Do not use a single flattened label. This answers "Manifests whose tagged subjects include a central bank, from any source".

### How a lookup behaves

- It matches the canonical name and its aliases as a case-insensitive substring. It ranks rows by similarity. Prefer rows with `canonical_match: true`, and check `canonical_match_found` in the response. A loose match is not the entity you asked for. Subsidiaries and brands that roll up to a parent are not separate filter targets.
- An unknown name returns an empty list with zero usage. It is not an error.
- The Tag search is narrow for abstract concepts on purpose. It has named entities and a curated set of macro-economic and financial topics such as `inflation` or `monetary_policy`. It does **not** have media-format concepts, so `search=podcast` finds no "podcast" topic. For a format, use `media_format`.

### Using Tags in a pull

| Field | Behavior |
| --- | --- |
| `tag_names` | Exact match against the Tag graph, after alias resolution. No fuzzy expansion. |
| `tag_ids` | The same match by ID. Pass IDs as strings. |
| `tag_type` | Pins name resolution to one type. |
| `tag_logic` | `and` requires every named Tag in the same Manifest (co-mentions). `or` (the default) matches any. |
| `exclude_tag_names`, `exclude_tag_ids` | Best-effort exclusion. |

If no name in `tag_names` resolves, the call fails closed with `tag_names_unresolved`. The error lists the names it could not resolve. With `or`, a mix of resolved and unresolved names runs the resolved names and lists the rest. With `and`, the server never drops an unknown required Tag to broaden the result.

### `tag_names` and `query` are different engines

`tag_names` is an exact census of a canonical Tag. `query` is semantic search over the Manifest index. They can disagree on the same phrase, and that is correct.

If you use both, the server intersects them. This gives the tightest result. Use `tag_names` when you know the canonical name. Use `query` for an idea that has no single Tag. `coverage.relevance_model` in the response tells you which engine ran.

### Join back from a Manifest

Every Manifest that matched a Tag has `tag_ids`, `tag_names` and `tag_types`. The arrays are index-aligned and ordered by `tag_id`.

The Manifest also has `tag_quality`. This is a list of self-contained objects. Each object gives the `role` of one Tag (`primary` or `supporting`), its `score` and its `rank`.

To find more content about a person you read about, take that Tag from `tag_quality`. Pass it to a new pull as `tag_ids`. A Manifest with more than 15 Tags can have trimmed arrays in compact views. For a specific Tag, use `tag_quality`.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| Empty Tag lookup | The name is not a canonical Tag, or is a brand under a parent | Try the parent organization, or the common alias. Do not substitute a similar name. |
| `tag_names_unresolved` | None of the names resolved | Fix the names from a lookup. Nothing was billed. |
| A count much lower than expected | `tag_logic: "and"`, or `tag_names` and `query` were combined | Check which engine and logic you used. |
| Wrong entity, same name | A name that fits several Tags | Pin `tag_type`, or choose by `tag_id` from the lookup. |
| `context_unigram_scope_too_broad` | A bare one-word `query` with no resolved Tag | Add a resolved Tag with `tag_names`, or make the phrase more specific. |
| Zipped Tag arrays disagree | A Manifest with more than 15 Tags in a compact view | Read `tag_quality` instead. |

## Make it good for your user

If a name can mean two things, ask. "Do you mean Apple the company, or Apple Records?" takes a second and prevents a wrong answer. If a name resolves, repeat the canonical name to your user. Then your user can see what you searched for. If the name resolves to nothing, say so and ask for another spelling.

## Next guide

[The Manifest filter cookbook](/agent-resources/manifests-filter-cookbook): every filter on a Manifest query, how they combine, and recipes for real questions.