---
title: "Personalize your site"
url: "https://developers.contentstack.com/paths/personalize-your-site"
type: "path_full"
level: "advanced"
outcome: "A site that serves entry variants from the edge, tracks impressions and conversions, and queries content by taxonomy."
steps:
  - "https://developers.contentstack.com/blog/client-static-server-or-edge-choosing-a-personalize-architecture"
  - "https://developers.contentstack.com/guides/personalize-with-ssr-at-the-edge"
  - "https://developers.contentstack.com/guides/querying-content-by-taxonomy"
updated: "2026-11-15T11:47:33.209Z"
---

# Personalize your site

- **Level:** Advanced
- **Steps:** 3
- **Overview:** https://developers.contentstack.com/paths/personalize-your-site.md

---

Choose a Personalize architecture, implement server-side personalization at the edge, and build the taxonomy-driven queries that feed personalized listings.

**You'll end up with:** A site that serves entry variants from the edge, tracks impressions and conversions, and queries content by taxonomy.

## Table of Contents

1. Client, static, server or edge? Choosing a Personalize architecture
2. Personalize with server-side rendering at the edge
3. Querying content by taxonomy


---

## Step 1: Client, static, server or edge? Choosing a Personalize architecture

- **Source:** https://developers.contentstack.com/blog/client-static-server-or-edge-choosing-a-personalize-architecture
- **Checkpoint:** You know which Personalize architecture fits your rendering model.

- **Authors:** Tim Benniks
- **Published:** 2026-11-21T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:35.429Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** personalization, headless

---

Where you resolve variants matters more than any other Personalize decision you make. It decides whether visitors see a flash of the wrong headline, whether your CDN can cache anything, and what search engines index. The SDK calls are almost the same in every setup. The architecture around them is where projects go right or wrong.

## The short version

There are four ways to wire up Contentstack Personalize, and I recommend them in this order:

- SSR at the edge. An edge function resolves variants, the origin renders, the CDN caches per variant. Use it unless you cannot run code in front of your origin.


- SSR without an edge. The origin resolves variants on every request. No flicker, but you build your own caching.


- CSR on top of SSG. Static pages from the CDN, personalization in the browser afterwards. Fast first paint, visible swap.


- Pure CSR. Everything in the browser. Only when there is no server in the picture at all.



The rest of this post explains why.

## What actually differs

Every Personalize setup does the same three things: get a manifest from the Personalize Edge API, turn it into variant aliases like cs_personalize_a_0, and pass those aliases to the Content Delivery API (CDA) with variants(). The CDA returns the base entry merged with the variant overrides.

The only question is where those steps run and when the HTML is produced. Move them later in the request and you get flicker. Move them earlier and you need infrastructure. Put them in the wrong layer and you lose caching.

## Client-side rendering

The browser loads the page with base content, initializes the SDK, fetches the manifest, fetches entry variants from the CDA and re-renders.

It is the easiest to add to an existing single-page app. A few SDK calls and you are personalizing. That is where the good news ends.

The visitor sees base content, then the swap. Skeleton loaders and opacity: 0 on personalized sections make it less ugly, but the two-phase render stays. Nothing personalized can be cached, because every variant fetch happens per visitor from the browser. Search engines see base content only. And every page load waits for two round trips before the right content appears.

There is also a Lytics catch. The cs-lytics-audiences cookie is written by the Lytics tag in the browser. If the Personalize SDK initializes before the tag fires, Lytics audiences do not evaluate on that load.

I would only pick pure CSR when the app is a single-page app with no server rendering path and adding one is blocked, not just inconvenient.

## Static generation with client-side personalization

This is CSR with a better starting point. The build produces static HTML with base content, the CDN serves it fast, and the browser applies personalization on top.

You keep fast, cacheable static pages and an origin that is only a build target. For sites already on static generation, it is the cheapest way to start.

The flicker is still there. The static page is visible before the variant arrives, which is fine for a sidebar recommendation and bad for a hero banner. Search engines index base content, not variants. And base content changes need a rebuild, while personalization decisions update in real time, so the two halves of the page change on different schedules.

Pick this when time to first byte is your top concern, the site is already static, and the personalized parts sit below the fold.

## Server-side rendering at the origin

The origin calls the Personalize Edge API for every request, gets the manifest, fetches entry variants and renders HTML. No flicker, and search engines get real HTML.

The cost is caching. A standard CDN cache keyed on the URL would serve one visitor's variant to everyone. So you either skip the cache and let every request hit your origin, or build a cache layer that includes variants in the key, with TTLs, invalidation and monitoring for the number of combinations. At any real traffic level, the origin becomes the bottleneck.

The origin does not need to be JavaScript. The Edge SDK wraps an HTTP API, so a Java, .NET or Go server can call the manifest endpoint and build the aliases itself.

Pick this when you have server rendering but genuinely nowhere to run edge code, such as a self-hosted setup behind a plain load balancer.

## Server-side rendering at the edge

An edge function runs before the CDN cache. It initializes the Edge SDK with the incoming request, gets the manifest, and rewrites the URL to something like /pricing?personalize_variants=a_0,b_1. The CDN uses that rewritten URL as the cache key. On a miss, the origin reads the parameter, calls variants() and renders.

```javascript
const sdk = await Personalize.init(projectUid, { request });
url.searchParams.set(sdk.VARIANT_QUERY_PARAM, sdk.getVariantParam());
const response = await fetch(new Request(url.toString(), request));
```

That is the core of it. Everyone who resolves to a_0,b_1 shares one cached page. The origin only renders on a cache miss and never sees a user ID. No flicker, full SEO, and the decision happens close to the visitor.

The trade-offs are real but small. You need an edge layer: Launch Edge Functions, Vercel middleware, Netlify Edge Functions, Cloudflare Workers, Fastly, Akamai or CloudFront all work. Tracking impressions and conversions still happens in the browser, because the edge cannot know what was seen or clicked. Every variant combination is a separate cache entry, so dozens of overlapping experiences fragment your cache. And on Launch specifically, Next.js middleware runs on the server, so the logic goes in a Launch Edge Function.

Since the origin only reads a query parameter, this also works in front of a non-JavaScript backend. The edge function is a separate deployment that the origin does not need to know about.

## Side by side


CSR

CSR + SSG

SSR

SSR at the edge

Flicker

Yes

Yes

No

No

SEO on variant content

Poor

Base content only

Full

Full

CDN caching

None for personalized content

Static shell only

Only with a custom cache layer

Per variant combination

Origin load

Low

Low

Every request

Cache misses only

Extra latency

Two browser round trips before content

Same, after the static paint

Edge API call per request

Edge API call at the edge

Complexity

Low

Medium, two render phases

Medium, custom caching

Low after a one-time edge setup

Infrastructure

None

Static hosting

Server

Server plus edge layer

Use it for

Last resort SPAs

Static sites, below-the-fold widgets

No edge available

Almost everything else

## How I would decide

I ask two questions.

Can you run code in front of your origin? If yes, use SSR at the edge. That includes non-JavaScript backends, because the edge function is separate from the origin.

If not, do you render on the server? If yes, use SSR at the origin and plan your cache key around variants from day one. If no, use static generation with client-side personalization, and keep personalized content out of the hero.

Pure CSR is what is left when the answer to both is no.

For native mobile apps, the question looks different: call the Personalize Edge API directly from the device. It is one hop, close to the user, and there is no HTML to cache. Put a small edge proxy in between only if you need to hide credentials or enforce your own rate limits.

## Where to go from here

If you are going the edge route, the guide [Personalize with server-side rendering at the edge](/guides/personalize-with-ssr-at-the-edge) builds the whole thing on Next.js and Launch: the edge function, entry variants with variants(), cache headers, tracking and layered experiences. The chapter on [setting up the Edge SDK](/guides/personalize-with-ssr-at-the-edge/set-up-the-edge-sdk) is where to start if you already know the concepts.

For the bigger picture of how the CMS, Personalize and Lytics divide the work, read [Understanding how Contentstack CMS, Personalize and Lytics work together](/blog/understanding-how-contentstack-cms-personalize-and-lytics-work-together).

My take: the edge pattern looks like the advanced option, and it is the simplest one to run in production. The setup is one edge function and one query parameter on the origin. After that, marketers add experiences and you do not touch the code.



---

## Do this with AI

Install the personalize and cms-variants-personalization skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Personalization Strategist profile in MCP Profile Hub. Then ask your agent:

> Review the experiences in my Personalize project and the pages they target, and recommend client-side, static, server or edge rendering for each, with the caching trade-off.

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




---

## Frequently asked questions

### Which Personalize architecture should I start with?

SSR at the edge, unless you cannot run any code in front of your origin. It is the only option without flicker that still caches at the CDN.

### Does my backend have to be JavaScript to use the edge pattern?

No. The Edge SDK runs in the edge layer. Your origin only reads a query parameter and passes variant aliases to the Content Delivery API.

### Why does client-side personalization flicker?

The browser renders the base content first, then asks Personalize for variants, fetches them and re-renders. The swap is visible.

### Can a statically generated site use Personalize?

Yes, by personalizing client-side on top of the static page. You keep fast static delivery but accept flicker, and search engines only see base content.


---

## Step 2: Personalize with server-side rendering at the edge

- **Source:** https://developers.contentstack.com/guides/personalize-with-ssr-at-the-edge
- **Checkpoint:** Variants resolve at the edge and impressions and conversions are tracked.

- **Authors:** Tim Benniks
- **Published:** 2026-11-26T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:15.142Z
- **Level:** Advanced
- **Intent:** Build
- **Tags:** personalization, sdk, next

---

> **Full guide available:** [View all 5 chapters in one document](https://developers.contentstack.com/guides/personalize-with-ssr-at-the-edge/full.md)

Personalization usually breaks one of three things: page speed, caching or SEO. Run it in the browser and you get a flash of default content before the variant appears. Run it on the origin for every request and you lose your CDN cache. Personalize avoids both if you split the work: an edge function decides which variants a visitor gets, and the origin renders those variants as if they were normal content.

This guide builds that setup on Next.js and Contentstack Launch. The same split works on Vercel, Netlify, Cloudflare Workers and other edge runtimes, and the guide calls out where they differ.

## What you'll learn

- How Personalize turns a visitor into a set of variant aliases


- How to run the Personalize Edge SDK in a Launch Edge Function


- How to fetch entry variants with the Delivery SDK and cache the result per variant


- How to track impressions and conversions from the browser


- How priority decides what renders when experiences overlap



## How the pieces fit

Every page request goes through the same path. The edge function asks the Personalize Edge API for the visitor's manifest, writes the active variants into a query parameter, and forwards the request. The CDN treats that rewritten URL as the cache key. On a miss, the origin reads the parameter, asks the Content Delivery API (CDA) for the matching entry variants and renders HTML.

sequenceDiagram    participant B as Browser    participant E as Edge function    participant P as Personalize Edge API    participant C as CDN cache    participant O as Next.js origin    participant D as Content Delivery API    B->>E: GET /pricing (cookies)    E->>P: Fetch manifest for this visitor    P-->>E: Active variant per experience    E->>C: GET /pricing?personalize_variants=a_0,b_1    alt cache hit        C-->>E: Cached personalized HTML    else cache miss        C->>O: Forward request        O->>D: Fetch entries with variant aliases        D-->>O: Merged entry variants        O-->>C: HTML plus s-maxage        C-->>E: Personalized HTML    end    E-->>B: HTML plus Personalize cookies    B->>P: Impressions and conversionsThe origin never sees a user ID or an audience. It only sees a_0,b_1, which is why the response is safe to cache and share with every visitor who resolved to the same variants.

## The chapters

Each chapter covers one part of the flow:

- [How Personalize resolves variants](/guides/personalize-with-ssr-at-the-edge/how-personalize-resolves-variants) explains projects, attributes, audiences, experiences and how a variant alias maps to a CMS entry variant. Read it first if Personalize is new to you.


- [Set up the Edge SDK](/guides/personalize-with-ssr-at-the-edge/set-up-the-edge-sdk) builds the Launch Edge Function: initialize the SDK with the request, rewrite the URL, and write the user and manifest cookies.


- [Fetch entry variants](/guides/personalize-with-ssr-at-the-edge/fetch-entry-variants) reads the parameter on the origin, passes aliases to variants(), and sets cache headers that work when the response varies per variant.


- [Track impressions and conversions](/guides/personalize-with-ssr-at-the-edge/track-impressions-and-conversions) wires up the browser SDK so A/B tests and analytics have data.


- [Layered and prioritized experiences](/guides/personalize-with-ssr-at-the-edge/layered-and-prioritized-experiences) covers several experiences on one page, priority, and when to pick segmented versus A/B.



Production note: The code uses the instance API of @contentstack/personalize-edge-sdk (version 1.0.9 and later), where Personalize.init() returns an SDK instance. The older global methods such as Personalize.getVariantAliases() still exist but are deprecated, and they share state across requests at the edge.

If you are still deciding whether edge rendering is right for your project, read [Client, static, server or edge? Choosing a Personalize architecture](/blog/client-static-server-or-edge-choosing-a-personalize-architecture) first. For how Personalize relates to the CMS and Lytics, see [Understanding how Contentstack CMS, Personalize and Lytics work together](/blog/understanding-how-contentstack-cms-personalize-and-lytics-work-together).

## Key takeaways

- The edge function decides, the origin renders, the browser reports.


- Variants travel as a query parameter (personalize_variants), so the CDN caches one page per variant combination.


- The origin needs no Personalize credentials and no user context.


- On Launch, use an Edge Function in functions/[proxy].edge.js, not Next.js middleware.


- Use the SDK instance returned by Personalize.init(), not the deprecated global methods.





---

## Do this with AI

Install the personalize and cms-variants-personalization skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Personalization Strategist profile in MCP Profile Hub. Then ask your agent:

> List the active experiences in my Personalize project with their type, priority and variant aliases, and map each alias to the CMS entry variants it should load.

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




---

## Frequently asked questions

### Why resolve variants at the edge instead of in the browser?

The page arrives already personalized, so there is no flicker, search engines see real HTML, and the CDN can cache one copy per variant combination.

### Does my origin need the Personalize SDK?

Only for one static helper that turns the variant query parameter into aliases. The origin never calls the Personalize Edge API.

### Can I use Next.js middleware on Launch for this?

No. On Launch, Next.js middleware runs on the server, not at the edge, so use a Launch Edge Function instead.

### Where do impressions and conversions get tracked?

In the browser. The edge function picks variants; the browser SDK reports what the visitor saw and did.


---

## Step 3: Querying content by taxonomy

- **Source:** https://developers.contentstack.com/guides/querying-content-by-taxonomy
- **Checkpoint:** Listings are filtered by taxonomy terms through the Delivery API.

- **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.

