--- title: "Taxonomy" description: "Taxonomy" url: "https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/dot-net/reference/taxonomy" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-09-14" --- # Taxonomy ## Taxonomy [Taxonomy](/docs/headless-cms/about-taxonomy) helps you categorize pieces of content within your stack to facilitate easy navigation and retrieval of information. This class supports two use cases: filtering entries by taxonomy terms, and fetching a specific published taxonomy (and its terms) directly from the CDA. **Note:** All methods in the Query section are applicable for taxonomy-based filtering as well. **Instance State** * Call stack.Taxonomies() without a UID to either filter entries by taxonomy terms, using EqualAndBelow, Below, EqualAndAbove, and Above, or list all published taxonomies, using Find. * Call stack.Taxonomies(uid) with a UID to fetch a specific published taxonomy or navigate to its terms, using Fetch, Term, and Terms. * Fetch, Term, and Terms all throw TaxonomyException if called on a Taxonomy instance created via the zero-arg Taxonomies(), since those methods require a UID. * Find throws TaxonomyException if called on a Taxonomy instance created via Taxonomies(uid), since listing all taxonomies requires an unscoped instance. ## EqualAndBelow The EqualAndBelow method retrieves all entries for a specific taxonomy that match a specific term and its descendant terms, requiring only the target term. **Note:** This query is applicable for the stack.Taxonomies() and stack.ContentType('uid').Query() methods. ``` ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); Taxonomy csQuery = stack.Taxonomies(); csQuery.EqualAndBelow("taxonomies.taxonomy_uid", "term_uid"); csQuery.Find().ContinueWith((queryResult) => { //Your callback code. }); ``` Enter the UID of the taxonomy Enter the UID of the term ## Below The Below method retrieves all entries for a specific taxonomy that match all of their descendant terms by specifying only the target term and a specific level. **Note:** If you don't specify the level, the default behavior is to retrieve terms up to level 10. ``` ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); Taxonomy csQuery = stack.Taxonomies(); csQuery.Below("taxonomies.taxonomy_uid", "term_uid"); csQuery.Find().ContinueWith((queryResult) => { //Your callback code. }); ``` Enter the UID of the taxonomy Enter the UID of the term ## EqualAndAbove The EqualAndAbove method retrieves all entries for a specific taxonomy that match a specific term and all its ancestor terms, requiring only the target term and a specified level. **Note:** If you don't specify the level, the default behavior is to retrieve terms up to level 10. ``` ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); Taxonomy csQuery = stack.Taxonomies(); csQuery.EqualAndAbove("taxonomies.taxonomy_uid", "term_uid"); csQuery.Find().ContinueWith((queryResult) => { //Your callback code. }); ``` Enter the UID of the taxonomy Enter the UID of the term ## Above The Above method retrieves all entries for a specific taxonomy that match only the parent terms of a specified target term, excluding the target term itself and a specified level. **Note:** If you don't specify the level, the default behavior is to retrieve terms up to level 10. ``` ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); Taxonomy csQuery = stack.Taxonomies(); csQuery.Above("taxonomies.taxonomy_uid", "term_uid"); csQuery.Find().ContinueWith((queryResult) => { //Your callback code. }); ``` Enter the UID of the taxonomy Enter the UID of the term ## SetLocale The SetLocale method sets the locale for the taxonomy fetch request. Passing a null or empty value is treated as a no-op. Chain this method before calling Fetch. ``` ValidationNo exception is thrown for a null or empty locale. It's treated as a no-op. BehaviorClient-side only. Sets a pending query parameter. No HTTP call is made until Fetch is called. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); var taxonomy = await stack.Taxonomies("taxonomy_uid").SetLocale("hi-in").Fetch(); ``` Locale code (for example, "hi-in" or "en-us") ## IncludeFallback The IncludeFallback method falls back to the master locale when the taxonomy is not published in the requested locale. It can be used with or without SetLocale. Chain this method before calling Fetch. ``` ValidationTakes no parameters, so there's nothing to validate. BehaviorClient-side only. Unconditionally sets include_fallback=true as a pending query parameter. No HTTP call is made until Fetch is called. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); var taxonomy = await stack.Taxonomies("taxonomy_uid").SetLocale("hi-in").IncludeFallback().Fetch(); ``` ## AddParam The AddParam method adds a custom query parameter to the taxonomy fetch request. Chain this method before calling Fetch. ``` ValidationNo SDK-level null check is performed on key or value. BehaviorClient-side only. Sets an arbitrary pending query parameter. No HTTP call is made until Fetch is called. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); var taxonomy = await stack.Taxonomies("taxonomy_uid").AddParam("include_branch", "true").Fetch(); ``` Query parameter key Query parameter value ## Fetch The Fetch method fetches a published taxonomy by its UID from the CDA. It requires the taxonomy to have been initialized via stack.Taxonomies("uid"). Use SetLocale, IncludeFallback, and AddParam to configure the request before calling Fetch. ``` ValidationThrows TaxonomyException if the Taxonomy was created through the zero-arg Taxonomies() (no UID set), because Fetch needs a specific taxonomy to request. See Delivery API Errors for general request errors. BehaviorMakes one HTTP GET request to /taxonomies/{uid}. The response is unwrapped at the $.taxonomy JSON token before deserializing to T, falling back to the raw response object if that token is absent. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); var taxonomy = await stack.Taxonomies("taxonomy_uid").Fetch(); var localized = await stack.Taxonomies("taxonomy_uid").SetLocale("hi-in").Fetch(); var withFallback = await stack.Taxonomies("taxonomy_uid").SetLocale("hi-in").IncludeFallback().Fetch(); ``` ## Find The Find method fetches all published taxonomies from the CDA. It is valid only on an unscoped Taxonomy instance, created via stack.Taxonomies() with no UID. Use AddParam (for example, "skip", "limit", "include\_count") to configure pagination before calling Find. ``` ValidationThrows TaxonomyException if the Taxonomy was created through Taxonomies(uid) (a UID was set), because Find lists taxonomies in general and does not operate on a single taxonomy. BehaviorMakes one HTTP GET request to /taxonomies. The response is unwrapped at the $.taxonomies JSON token into the returned collection's Items. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); var result = await stack.Taxonomies().Find(); var page = await stack.Taxonomies().AddParam("skip", "0").AddParam("limit", "10").Find(); ``` ## Term The Term method returns a Term instance scoped to the given term UID within this taxonomy. It requires the taxonomy to have been initialized via stack.Taxonomies("uid"). ``` ValidationThrows TaxonomyException if the Taxonomy has no UID (same reason as Fetch). Separately, the returned Term object's own constructor throws TaxonomyException if termUid is null or empty. BehaviorClient-side only. Constructs a Term instance. No HTTP call is made. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); Term term = stack.Taxonomies("taxonomy_uid").Term("term_uid"); ``` UID of the term to retrieve ## Terms The Terms method returns a TermQuery instance for listing all published terms within this taxonomy. It requires the taxonomy to have been initialized via stack.Taxonomies("uid"). Chain SetLocale and IncludeFallback on the returned TermQuery before calling Find. ``` ValidationThrows TaxonomyException if the Taxonomy has no UID (same reason as Fetch). BehaviorClient-side only. Constructs a TermQuery instance. No HTTP call is made. ExampleContentstackClient stack = new ContentstackClient("api_key", "delivery_token", "environment"); TermQuery termQuery = stack.Taxonomies("taxonomy_uid").Terms(); ``` ## Taxonomy | .NET Delivery SDK | Contentstack Taxonomy lets you categorize stack content in the .NET Delivery SDK, supporting taxonomy-based filtering for easy navigation and retrieval.