Filter content to get what you need

Jan Cerman

11 minutes

0% complete

The Delivery API provides several filters to help you refine your requests based on your requirements. To choose the right one, think about what you know about the content you want to get. There’s a filter for every use case.Find a scenario relevant to you and adjust the code samples to get the content you need.

Filter by item ID or a codename

To get an item based on its identifier (like ID or codename), use the equals filter. For example, if you need to get an item by its internal ID, you match the item's ID (found in system.id) against the ID value you have.

var result = await client.GetItems()
    .Where(item => item.System("id").IsEqualTo("2f7288a1-cfc8-47be-9bf1-b1d312f7da18"))
    .ExecuteAsync();

Tip: This approach works equally well for other system properties of the content item object. For example, system.workflow_step, system.collection, system.last_modified.

If you have multiple identifiers of a single type (for example, only IDs or codenames) and want to retrieve them in a single request, use the in filter.

// Gets three items by their codenames. The codenames are unique per environment.
var result = await client.GetItems()
    .Where(item => item.System("codename").IsIn("delivery_api", "get_content", "hello_world"))
    .ExecuteAsync();

If you know the item's codename, we recommend you retrieve the content item directly for better performance.

Filter by content types

To get items based on a single content type, specify the content type's codename (system.type) using the equals filter.

// Gets items based on the "product" type
var result = await client.GetItems()
    .Where(item => item.System("type").IsEqualTo("product"))
    .ExecuteAsync();

// Note: When using generated models with [ContentTypeCodename("product")] attribute,
// the type filter is added automatically and this manual filter is not needed.
var result = await client.GetItems<Product>()
    .ExecuteAsync();

To get items based on multiple content types, specify the content types' codenames using the in filter.

// Gets items based on the types Product, Article, and News
var result = await client.GetItems()
    .Where(item => item.System("type").IsIn("product", "article", "news"))
    .ExecuteAsync();

Filter by date & time and numbers

To get items by a datetime value, you can use one of the comparison filters. This lets you retrieve content modified or released before or after a certain date. The following code shows the filters used on the last content modification date and a date & time element.

// Note: Date & time element values are provided by users and stored with minute precision.
// The system.last_modified value reflects last content change to an item and is stored with second precision.

// Gets items modified after May 9 2020, 9 am UTC (using DateTime overload)
var result = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsGreaterThan(new DateTime(2020, 5, 9, 9, 0, 0, DateTimeKind.Utc)))
    .ExecuteAsync();

// Gets items released at or after May 9 2020, 7 am UTC (using string overload)
var result = await client.GetItems()
    .Where(item => item.Element("release_date")
        .IsGreaterThanOrEqualTo("2020-05-09T07:00:00Z"))
    .ExecuteAsync();

// Gets items modified before May 5 2020 UTC. Last match would be at 2020-05-04T23:59:59.
// Date-only string — no time component appended by the SDK.
var result = await client.GetItems()
    .Where(item => item.System("last_modified").IsLessThan("2020-05-05"))
    .ExecuteAsync();

// Gets items released at or before May 5 2020 10:30 am UTC (SDK implicitly serializes DateTime to UTC)
var result = await client.GetItems()
    .Where(item => item.Element("release_date")
        .IsLessThanOrEqualTo(new DateTime(2020, 5, 5, 10, 30, 0)))
    .ExecuteAsync();

Tip: Use the same approach for number elements.

Filter by a range of dates and numbers

To get items based on a date range, you need to specify two datetime values using the range filter.

// Note: Date & time element values are provided by users and stored with minute precision. The system.last_modified value reflects last content change to an item and is stored with ms precision.

// Gets items modified between May 5, 2020 10:30 UTC and May 7, 2020 7:00 UTC (inclusive)
// Using string overload — values passed through as-is to the API
var result = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsWithinRange("2020-05-05T10:30:00Z", "2020-05-07T07:00:00Z"))
    .ExecuteAsync();

// Equivalent using DateTime overload (SDK implicitly serializes DateTime as UTC if not specified)
var result2 = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsWithinRange(
            new DateTime(2020, 5, 5, 10, 30, 0),
            new DateTime(2020, 5, 7, 7, 0, 0)))
    .ExecuteAsync();

To get items based on a number range, you need to specify two numbers. The numbers can be either integers like 3 or floats like 3.14.

// Gets items whose rating is at least 6.5 and at most 9
var result = await client.GetItems()
    .Where(item => item.Element("product_rating").IsWithinRange(6.5, 9))
    .ExecuteAsync();

Filter by text and rich text

To get items based on the value of a text or rich text element, you need to specify the value using the equals filter.

The same approach also applies to custom elements.

// Gets items whose Title element value equals "Hello World"
var result = await client.GetItems()
    .Where(item => item.Element("title").IsEqualTo("Hello World"))
    .ExecuteAsync();

Filter by taxonomy and multiple choice

To get items tagged with specific taxonomy terms, you need to specify the terms using the contains, any, or all filters.

// Note: Filters work with codenames of the tags.

// Gets items tagged with one specific tag
var result1 = await client.GetItems()
    .Where(item => item.Element("tags").Contains("kontent_ai"))
    .ExecuteAsync();

// Gets items tagged with all specified tags
var result2 = await client.GetItems()
    .Where(item => item.Element("tags").ContainsAll("kontent_ai", "cms"))
    .ExecuteAsync();

// Gets items tagged with at least one tag from the list
var result3 = await client.GetItems()
    .Where(item => item.Element("tags").ContainsAny("headless", "cms"))
    .ExecuteAsync();

Also works for the multiple choice and custom elementsUse the same approach to get items based on a specific value or values of the multiple choice elements. For custom elements, the contains, any, and all filters work only if the element’s value is a stringified array of strings. For example, "[\"DE\",\"US\",\"UK\"]".

Filter by URL slug

The URL slug element value is stored in the same way as the values of text elements. This means the approach to getting items by a specific URL slug is the same, using the equals filter.

// Gets items in default language with the URL slug element equal to 'sample-url-slug'
var result = await client.GetItems()
    .Where(item => item.Element("url_slug").IsEqualTo("sample-url-slug"))
    .ExecuteAsync();

To ensure you get content in a specific language, use the language parameter in your requests.

Filter by parent items

When you link multiple items together using the linked items elements, you can retrieve your items based on their relationships.Examples:

Filter by where items are used – You can have a linked items element for navigation. Each linked item represents a navigation item in a hierarchy.
Filter by article's author – You can have several articles written by a single author, Jane. Each article has a linked items element named Author, containing a reference to the content item that represents the author Jane.
Filter by subpages – You can retrieve subpages the same way as your linked items. For example, you can have various insurance-related pages linked in multiple places on your website.

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!

Filter content to get what you need

Jan Cerman

11 minutes

0% complete

Filter by item ID or a codename

var result = await client.GetItems()
    .Where(item => item.System("id").IsEqualTo("2f7288a1-cfc8-47be-9bf1-b1d312f7da18"))
    .ExecuteAsync();

Tip: This approach works equally well for other system properties of the content item object. For example, system.workflow_step, system.collection, system.last_modified.

If you have multiple identifiers of a single type (for example, only IDs or codenames) and want to retrieve them in a single request, use the in filter.

// Gets three items by their codenames. The codenames are unique per environment.
var result = await client.GetItems()
    .Where(item => item.System("codename").IsIn("delivery_api", "get_content", "hello_world"))
    .ExecuteAsync();

If you know the item's codename, we recommend you retrieve the content item directly for better performance.

Filter by content types

To get items based on a single content type, specify the content type's codename (system.type) using the equals filter.

// Gets items based on the "product" type
var result = await client.GetItems()
    .Where(item => item.System("type").IsEqualTo("product"))
    .ExecuteAsync();

// Note: When using generated models with [ContentTypeCodename("product")] attribute,
// the type filter is added automatically and this manual filter is not needed.
var result = await client.GetItems<Product>()
    .ExecuteAsync();

To get items based on multiple content types, specify the content types' codenames using the in filter.

// Gets items based on the types Product, Article, and News
var result = await client.GetItems()
    .Where(item => item.System("type").IsIn("product", "article", "news"))
    .ExecuteAsync();

Filter by date & time and numbers

// Note: Date & time element values are provided by users and stored with minute precision.
// The system.last_modified value reflects last content change to an item and is stored with second precision.

// Gets items modified after May 9 2020, 9 am UTC (using DateTime overload)
var result = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsGreaterThan(new DateTime(2020, 5, 9, 9, 0, 0, DateTimeKind.Utc)))
    .ExecuteAsync();

// Gets items released at or after May 9 2020, 7 am UTC (using string overload)
var result = await client.GetItems()
    .Where(item => item.Element("release_date")
        .IsGreaterThanOrEqualTo("2020-05-09T07:00:00Z"))
    .ExecuteAsync();

// Gets items modified before May 5 2020 UTC. Last match would be at 2020-05-04T23:59:59.
// Date-only string — no time component appended by the SDK.
var result = await client.GetItems()
    .Where(item => item.System("last_modified").IsLessThan("2020-05-05"))
    .ExecuteAsync();

// Gets items released at or before May 5 2020 10:30 am UTC (SDK implicitly serializes DateTime to UTC)
var result = await client.GetItems()
    .Where(item => item.Element("release_date")
        .IsLessThanOrEqualTo(new DateTime(2020, 5, 5, 10, 30, 0)))
    .ExecuteAsync();

Tip: Use the same approach for number elements.

Filter by a range of dates and numbers

To get items based on a date range, you need to specify two datetime values using the range filter.

// Note: Date & time element values are provided by users and stored with minute precision. The system.last_modified value reflects last content change to an item and is stored with ms precision.

// Gets items modified between May 5, 2020 10:30 UTC and May 7, 2020 7:00 UTC (inclusive)
// Using string overload — values passed through as-is to the API
var result = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsWithinRange("2020-05-05T10:30:00Z", "2020-05-07T07:00:00Z"))
    .ExecuteAsync();

// Equivalent using DateTime overload (SDK implicitly serializes DateTime as UTC if not specified)
var result2 = await client.GetItems()
    .Where(item => item.System("last_modified")
        .IsWithinRange(
            new DateTime(2020, 5, 5, 10, 30, 0),
            new DateTime(2020, 5, 7, 7, 0, 0)))
    .ExecuteAsync();

To get items based on a number range, you need to specify two numbers. The numbers can be either integers like 3 or floats like 3.14.

// Gets items whose rating is at least 6.5 and at most 9
var result = await client.GetItems()
    .Where(item => item.Element("product_rating").IsWithinRange(6.5, 9))
    .ExecuteAsync();

Filter by text and rich text

To get items based on the value of a text or rich text element, you need to specify the value using the equals filter.

The same approach also applies to custom elements.

// Gets items whose Title element value equals "Hello World"
var result = await client.GetItems()
    .Where(item => item.Element("title").IsEqualTo("Hello World"))
    .ExecuteAsync();

Filter by taxonomy and multiple choice

To get items tagged with specific taxonomy terms, you need to specify the terms using the contains, any, or all filters.

// Note: Filters work with codenames of the tags.

// Gets items tagged with one specific tag
var result1 = await client.GetItems()
    .Where(item => item.Element("tags").Contains("kontent_ai"))
    .ExecuteAsync();

// Gets items tagged with all specified tags
var result2 = await client.GetItems()
    .Where(item => item.Element("tags").ContainsAll("kontent_ai", "cms"))
    .ExecuteAsync();

// Gets items tagged with at least one tag from the list
var result3 = await client.GetItems()
    .Where(item => item.Element("tags").ContainsAny("headless", "cms"))
    .ExecuteAsync();

Filter by URL slug

The URL slug element value is stored in the same way as the values of text elements. This means the approach to getting items by a specific URL slug is the same, using the equals filter.

// Gets items in default language with the URL slug element equal to 'sample-url-slug'
var result = await client.GetItems()
    .Where(item => item.Element("url_slug").IsEqualTo("sample-url-slug"))
    .ExecuteAsync();

To ensure you get content in a specific language, use the language parameter in your requests.

Filter by parent items

When you link multiple items together using the linked items elements, you can retrieve your items based on their relationships.Examples:

Filter by where items are used – You can have a linked items element for navigation. Each linked item represents a navigation item in a hierarchy.
Filter by article's author – You can have several articles written by a single author, Jane. Each article has a linked items element named Author, containing a reference to the content item that represents the author Jane.
Filter by subpages – You can retrieve subpages the same way as your linked items. For example, you can have various insurance-related pages linked in multiple places on your website.

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!