---
title: "Querying content by taxonomy"
url: "https://developers.contentstack.com/guides/querying-content-by-taxonomy"
type: "guide"
level: "intermediate"
intent: "build"
outcome: "You can filter entries by taxonomy terms through the Delivery API and the TypeScript Delivery SDK, and you know when to filter in the query and when to filter in memory."
prerequisites:
  - "A Contentstack stack with at least one taxonomy applied to a content type"
  - "Published entries tagged with terms from that taxonomy"
  - "A delivery token and environment for the stack"
  - "Working knowledge of the TypeScript Delivery SDK"
tags:
  - "taxonomy"
  - "api"
  - "sdk"
authors:
  - "Tim Benniks"
published: "2026-11-18T09:00:00.000Z"
updated: "2026-11-15T10:56:21.262Z"
---

# Querying content by taxonomy

- **Authors:** Tim Benniks
- **Published:** 2026-11-18T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:21.262Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** taxonomy, api, sdk

---

Most listing pages are a filter in disguise. "All beginner guides." "Everything about Next.js." "Blog posts in Europe, including the ones tagged Germany." Taxonomies let you express those filters once, in the stack, and query them from any content type with the same syntax.

This guide covers how taxonomy terms end up on entries, the query operators the Content Delivery API (CDA) supports, how to write them with the TypeScript Delivery SDK, and how developers.contentstack.com uses taxonomies to build its own filtered listings.

## What you'll learn

- How taxonomies, terms and entries relate


- How to filter entries by one term, several terms, or a combination of taxonomies


- How to query a term hierarchy with $eq_below, $below, $eq_above and $above


- How to query across content types with /taxonomies/entries


- How to write those queries with @contentstack/delivery-sdk


- When to filter in the query and when to filter in memory



## How taxonomies attach to entries

Contentstack concept: A taxonomy is a stack-level tree of terms. You create it once and attach it to any content type that needs it.

The taxonomy is not owned by a content type. If your stack has a level taxonomy with the terms beginner, intermediate and advanced, your guide, blogpost and kickstart content types can all use it. A term means the same thing everywhere, and a query for beginner works the same way on all three.

To use a taxonomy, add the Taxonomy field to a content type and pick which taxonomies editors can choose from. Editors then select terms in the entry editor. The entry stores its selection as a list of pairs:

```json
{
  "title": "Querying content by taxonomy",
  "taxonomies": [
    { "taxonomy_uid": "subjects", "term_uid": "taxonomy" },
    { "taxonomy_uid": "subjects", "term_uid": "api" },
    { "taxonomy_uid": "level", "term_uid": "intermediate" },
    { "taxonomy_uid": "intent", "term_uid": "build" }
  ]
}
```

The entry only stores UIDs. It does not store the term's position in the tree. That is why you can move a term to a different parent without rewriting every entry that uses it, and why hierarchical queries resolve the tree at query time.

If you are coming from WordPress, a taxonomy is close to a custom taxonomy with hierarchical terms. The difference is that in Contentstack you query it through the same API and query language you use for every other field.

## Filter on a single term

Every taxonomy query uses the field path taxonomies.<taxonomy_uid>. The simplest form matches entries that carry one term:

```bash
curl -G "https://cdn.contentstack.io/v3/content_types/guide/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"taxonomies.level": "beginner"}'
```

This returns every published guide entry tagged beginner in the level taxonomy. Use your region's CDA host if your stack is not in AWS North America.

## Match any of several terms with $in

$in matches entries that carry at least one of the listed terms in a taxonomy:

```json
{ "taxonomies.subjects": { "$in": ["taxonomy", "content_modeling"] } }
```

This is the operator behind a multi-select filter where checking two subjects should widen the results, not narrow them.

## Combine taxonomies with $and and $or

$and and $or take a list of conditions. Use them to combine terms from different taxonomies:

```json
{
  "$and": [
    { "taxonomies.level": "beginner" },
    { "taxonomies.intent": "build" }
  ]
}
```

That query returns entries that are both beginner level and build intent. Swap $and for $or to get entries that match either condition.

Watch for: $in on one taxonomy is an OR between terms. $and across taxonomies is an AND between facets. A typical filter UI needs both: OR inside a facet, AND between facets.

## Find entries that use a taxonomy at all

$exists matches entries that have any term from a taxonomy:

```json
{ "taxonomies.level": { "$exists": true } }
```

Use it for listings like "everything that has a level", or to check how many entries of a content type are tagged at all.

## Query a term hierarchy

Taxonomies are trees, and four operators let you query along the tree. Take a region taxonomy where europe has the children germany and france, and germany has the child berlin.

Operator

Matches entries tagged with

Example with europe or berlin

$eq_below

The term or any term below it

europe, germany, france, berlin

$below

Only the terms below it

germany, france, berlin

$eq_above

The term or any term above it

berlin, germany, europe

$above

Only the terms above it

germany, europe

All four accept an optional levels value that limits how far the query walks:

```json
{ "taxonomies.region": { "$eq_below": "europe", "levels": 1 } }
```

With levels: 1, the query matches europe, germany and france, but not berlin. If you leave levels out, the API walks up to 10 levels, which is also the maximum depth of a taxonomy.

$eq_below is the operator you want for landing pages. A page for "Europe" should show content tagged with any European country without you listing every country in the query.

## Query across content types

The examples above query one content type. To query every content type that uses a taxonomy, call the taxonomies entries endpoint with the same query syntax:

```bash
curl -G "https://cdn.contentstack.io/v3/taxonomies/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"taxonomies.level": {"$in": ["beginner"]}}'
```

This returns guides, blog posts and any other content type tagged beginner in one response. It is the cheapest way to build a "start here" page that mixes formats.

## Write the queries with the TypeScript Delivery SDK

The TypeScript Delivery SDK writes taxonomy filters with the same methods you use for other fields. Field paths with dots are valid, so taxonomies.level works like any field UID.

```typescript
import contentstack, {
  QueryOperation,
  TaxonomyQueryOperation,
} from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

// Single term
const beginnerGuides = await stack
  .contentType("guide")
  .entry()
  .query()
  .where("taxonomies.level", QueryOperation.EQUALS, "beginner")
  .find();

// Any of several terms ($in)
const modelingPosts = await stack
  .contentType("blogpost")
  .entry()
  .query()
  .containedIn("taxonomies.subjects", ["taxonomy", "content_modeling"])
  .find();

// Term and everything below it, two levels deep
const europe = await stack
  .contentType("article")
  .entry()
  .query()
  .where("taxonomies.region", TaxonomyQueryOperation.EQ_BELOW, "europe", { levels: 2 })
  .find();
```

The fourth argument of where() merges extra keys into the condition, which is how levels ends up next to $eq_below. exists("taxonomies.level") gives you $exists: true.

For $and and $or, build sub-queries and pass them to and() or or():

```typescript
const guides = stack.contentType("guide").entry();

const result = await guides
  .query()
  .and(
    guides.query().where("taxonomies.level", QueryOperation.EQUALS, "beginner"),
    guides.query().where("taxonomies.intent", QueryOperation.EQUALS, "build")
  )
  .find();
```

### Cross-type queries from TypeScript

stack.taxonomy() without a UID returns a TaxonomyQuery. In recent 5.x versions of the SDK, calling find() on it lists the stack's published taxonomies. It does not return entries, and it ignores conditions you added with where(). Check the behavior of the version you run. When you need entries from several content types in one call, a plain fetch against /v3/taxonomies/entries is short and predictable:

```typescript
const CDA_HOST = process.env.CONTENTSTACK_CDA_HOST ?? "https://cdn.contentstack.io";

export async function findEntriesByTaxonomy(query: Record<string, unknown>) {
  const params = new URLSearchParams({
    environment: process.env.CONTENTSTACK_ENVIRONMENT!,
    query: JSON.stringify(query),
  });

  const response = await fetch(`${CDA_HOST}/v3/taxonomies/entries?${params}`, {
    headers: {
      api_key: process.env.CONTENTSTACK_API_KEY!,
      access_token: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
    },
  });

  if (!response.ok) {
    throw new Error(`Taxonomy query failed: ${response.status}`);
  }

  return (await response.json()) as { entries: Record<string, unknown>[] };
}

const { entries } = await findEntriesByTaxonomy({
  "taxonomies.level": { "$in": ["beginner"] },
});
```

## Worked example: filtered listings on this site

developers.contentstack.com tags blog posts, guides, kickstarts and live streams with four taxonomies: subjects, technology, intent and level. Those terms drive the cards on listing pages, the level and intent filters on /search, and the level and intent lines in each page's markdown frontmatter.

Listing pages are built from a List block in the CMS. Its custom_card_query group holds the content type, a set of term UIDs, a limit, a sort order and a show_filters toggle. Editors build "All beginner guides" without a deploy.

Here is a simplified version of the server-side query for one List block. It fetches only the fields a card needs and filters by terms in the query:

```typescript
import { stack } from "./config";

const CARD_FIELDS = ["title", "url", "date", "taxonomies"];

interface CardQuery {
  contentType: "guide" | "blogpost";
  taxonomyUid: string;
  terms: string[];
  limit: number;
}

export async function getCards({ contentType, taxonomyUid, terms, limit }: CardQuery) {
  const query = stack
    .contentType(contentType)
    .entry()
    .only(CARD_FIELDS)
    .query()
    .orderByDescending("date")
    .limit(limit);

  if (terms.length > 0) {
    query.containedIn(`taxonomies.${taxonomyUid}`, terms);
  }

  const result = await query.find();
  return result.entries ?? [];
}
```

Because the filter runs in the query, limit() returns the right slice. Filter after the query instead and a limit of 10 can leave you with three cards.

The /search page takes a different route on purpose. It shows a count next to every level, intent, subject and technology term, and it updates those counts as you combine filters. A taxonomy query returns matching entries, not counts per term. So the site fetches one small dataset per content type (title, URL, taxonomies and a few card fields) and filters and counts in memory:

```typescript
type Entry = { taxonomies?: { taxonomy_uid: string; term_uid: string }[] };

function termsOf(entry: Entry, taxonomyUid: string) {
  return (entry.taxonomies ?? [])
    .filter((t) => t.taxonomy_uid === taxonomyUid)
    .map((t) => t.term_uid);
}

function countTerms(entries: Entry[], taxonomyUid: string) {
  const counts = new Map<string, number>();
  for (const entry of entries) {
    for (const term of termsOf(entry, taxonomyUid)) {
      counts.set(term, (counts.get(term) ?? 0) + 1);
    }
  }
  return counts;
}
```

That trade-off works because the content set is small: a few lean requests return every entry, and the server filters and counts in memory for each search. On a large catalog, filter in the query and get counts from a search index instead.

flowchart TD  A[Need a filtered list] --> B{Need counts per term?}  B -- No --> C{One content type?}  C -- Yes --> D[content_types/uid/entries with a taxonomy query]  C -- No --> E[taxonomies/entries with a taxonomy query]  B -- Yes --> F{Small dataset?}  F -- Yes --> G[Fetch minimal fields once, filter and count in memory]  F -- No --> H[Use a search index for facets]## Where people get confused

### Term UIDs versus term names

Queries use term UIDs, not the labels editors see. If an editor renames "Beginner" to "Getting started", the UID stays beginner and your queries keep working. Hardcode UIDs, never labels.

### Filtering after the query

Filtering in application code after a limit() drops results silently. Either filter in the query or fetch enough entries to cover the filter.

### Taxonomies and references

A taxonomy term is a label, not an entry. It has no fields of its own to render, so you do not need includeReference() to read taxonomy_uid and term_uid from an entry. If you need rich content per category (a description, an image, a landing page), model that as a content type and reference it. The [modeling decision guide](/guides/modular-blocks-references-or-global-fields) covers when to pick which.

## Limits to remember

- An entry can hold up to 25 terms. A Taxonomy field can set a lower maximum per taxonomy.


- A taxonomy can hold up to 10,000 terms, nested up to 10 levels deep.


- The number of taxonomies per stack depends on your plan.


- Queries go in the URL, and the CDA has an 8 KB URL limit. A long $in list or many $or branches can hit it.



## Key takeaways

- Taxonomies live at the stack level. One query syntax works across every content type that uses them.


- Filter with taxonomies.<taxonomy_uid>: a plain value for one term, $in for any of several, $and/$or to combine taxonomies, $exists for audits.


- Use $eq_below with levels for landing pages that cover a branch of the tree.


- Use /v3/taxonomies/entries to query across content types. In recent SDK versions, call it with fetch rather than stack.taxonomy().find().


- Filter in the query when you use limit(). Count in memory or in a search index when the UI needs facet counts.



## Next steps

- Read [Taxonomies are your query layer](/blog/taxonomies-are-your-query-layer) for why this site models its learning content with four taxonomies.


- Follow the [Personalize your site](/paths/personalize-your-site) path to combine taxonomy queries with personalized listings.


- Revisit [rewriting queries for the TypeScript Delivery SDK](/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk/rewrite-queries-pagination-sorting-and-field-selection) for the rest of the query API.





---

## Do this with AI

Install the cms-taxonomy and dx-delivery-sdk skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Explorer profile in MCP Profile Hub. Then ask your agent:

> Find all blog_post entries classified under any term in the frameworks taxonomy, child terms included, and write the Delivery SDK query that returns the same list.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Are taxonomies defined per content type?

No. A taxonomy lives at the stack level. You attach it to as many content types as you want, and every one of them shares the same terms.

### Which endpoint queries entries across content types by taxonomy?

GET /v3/taxonomies/entries with a query parameter. Per content type, use the normal /v3/content_types/{uid}/entries endpoint with the same query syntax.

### What does levels do in $eq_below and $below?

It limits how many levels of the hierarchy the operator walks. If you leave it out, the API walks up to 10 levels.

### Can a taxonomy query return facet counts?

No. A taxonomy query returns matching entries. If you need counts per term for a filter UI, count them yourself from the entries you fetched.

