Filter content items (examples)

July 8, 2022

Jan Cerman

5 min read

When building your apps, you'll use the Delivery REST API or Delivery GraphQL API to get content items. The Delivery APIs provide several filters to help you refine your requests based on your requirements.

If you select GraphQL as your tech stack above, you'll see sample GraphQL queries. These queries can be used in any app that supports GraphQL.

What do you know about the content you want to get? Find a relevant scenario below and adjust the code samples to get the content you need.

Item ID or 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.

GraphQL
# Gets an item by its internal ID
query GetArticleById {
  article_All(where: {_system_: {id: {eq: "2f7288a1-cfc8-47be-9bf1-b1d312f7da18"}}}) {
    items {
      title
    }
  }
}
# Gets an item by its internal ID
query GetArticleById {
  article_All(where: {_system_: {id: {eq: "2f7288a1-cfc8-47be-9bf1-b1d312f7da18"}}}) {
    items {
      title
    }
  }
}

Java
// Gets an item by its internal ID
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("system.id", "2f7288a1-cfc8-47be-9bf1-b1d312f7da18")
    .build()
);
// Gets an item by its internal ID
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("system.id", "2f7288a1-cfc8-47be-9bf1-b1d312f7da18")
    .build()
);

JavaScript
// Gets an item by its internal ID
const response = await deliveryClient.items()
  .equalsFilter('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18')
  .toPromise();
// Gets an item by its internal ID
const response = await deliveryClient.items()
  .equalsFilter('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18')
  .toPromise();

C#
// Gets an item by its internal ID
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("system.id", "2f7288a1-cfc8-47be-9bf1-b1d312f7da18")
);
// Gets an item by its internal ID
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("system.id", "2f7288a1-cfc8-47be-9bf1-b1d312f7da18")
);

PHP
// Gets an item by its internal ID
$items = $client->getItems((new QueryParams())
  ->equals('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18'));
// Gets an item by its internal ID
$items = $client->getItems((new QueryParams())
  ->equals('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18'));

cURL
# Gets an item by its internal ID
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.id=2f7288a1-cfc8-47be-9bf1-b1d312f7da18' \
  --header 'content-type: application/json'
# Gets an item by its internal ID
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.id=2f7288a1-cfc8-47be-9bf1-b1d312f7da18' \
  --header 'content-type: application/json'

Ruby
# Gets an item by its internal ID
delivery_client.items('system.id'.equals('2f7288a1-cfc8-47be-9bf1-b1d312f7da18'))
# Gets an item by its internal ID
delivery_client.items('system.id'.equals('2f7288a1-cfc8-47be-9bf1-b1d312f7da18'))

TypeScript
// Gets an item by its internal ID
const response = await deliveryClient.items()
  .equalsFilter('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18')
  .toPromise();
// Gets an item by its internal ID
const response = await deliveryClient.items()
  .equalsFilter('system.id', '2f7288a1-cfc8-47be-9bf1-b1d312f7da18')
  .toPromise();

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.

If you have multiple codenames of a single type and want to retrieve the items in a single request, use GraphQL aliases.

GraphQL
# Gets three articles by their codenames. Use GraphQL aliases to retrieve multiple items of the same type.
query GetArticlesByCodenames {
  helloWorldArticle: article(codename: "hello_world") {
    title
  }
  getContentArticle: article(codename: "get_content") {
    title
  }
  filterContentArticle: article(codename: "filter_content") {
    title
  }
}
# Gets three articles by their codenames. Use GraphQL aliases to retrieve multiple items of the same type.
query GetArticlesByCodenames {
  helloWorldArticle: article(codename: "hello_world") {
    title
  }
  getContentArticle: article(codename: "get_content") {
    title
  }
  filterContentArticle: article(codename: "filter_content") {
    title
  }
}

Java
// Gets three items by their codenames. The codenames are unique per project.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterIn("system.codename", "delivery_api", "get_content", "hello_world")
    .build()
);
// Gets three items by their codenames. The codenames are unique per project.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterIn("system.codename", "delivery_api", "get_content", "hello_world")
    .build()
);

JavaScript
// Gets three items by their codenames. The codenames are unique per project.
const response = await deliveryClient.items()
  .inFilter('system.codename', ['delivery_api', 'get_content', 'hello_world'])
  .toPromise();
// Gets three items by their codenames. The codenames are unique per project.
const response = await deliveryClient.items()
  .inFilter('system.codename', ['delivery_api', 'get_content', 'hello_world'])
  .toPromise();

C#
// Gets three items by their codenames. The codenames are unique per project.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new InFilter("system.codename", "delivery_api", "get_content", "hello_world")
);
// Gets three items by their codenames. The codenames are unique per project.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new InFilter("system.codename", "delivery_api", "get_content", "hello_world")
);

PHP
// Gets three items by their codenames. The codenames are unique per project.
$items = $client->getItems((new QueryParams())
  ->in('system.codename', ['delivery_api', 'get_content', 'hello_world']));
// Gets three items by their codenames. The codenames are unique per project.
$items = $client->getItems((new QueryParams())
  ->in('system.codename', ['delivery_api', 'get_content', 'hello_world']));

cURL
# Gets three items by their codenames. The codenames are unique per project.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.codename[in]=delivery_api,get_content,hello_world' \
  --header 'content-type: application/json'
# Gets three items by their codenames. The codenames are unique per project.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.codename[in]=delivery_api,get_content,hello_world' \
  --header 'content-type: application/json'

Ruby
# Gets three items by their codenames. The codenames are unique per project.
delivery_client.items('system.codename'.in('delivery_api', 'get_content', 'hello_world'))
# Gets three items by their codenames. The codenames are unique per project.
delivery_client.items('system.codename'.in('delivery_api', 'get_content', 'hello_world'))

TypeScript
// Gets three items by their codenames. The codenames are unique per project.
const response = await deliveryClient.items()
  .inFilter('system.codename', ['delivery_api', 'get_content', 'hello_world'])
  .toPromise();
// Gets three items by their codenames. The codenames are unique per project.
const response = await deliveryClient.items()
  .inFilter('system.codename', ['delivery_api', 'get_content', 'hello_world'])
  .toPromise();

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

Content types

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

To get items based on a single content type, use the root collection query for a specific type. For example, product_All.

GraphQL
# Gets items based on the type Product
query GetItemsByType {
    product_All { # Root collection query specifies the content type
        items {
            price
        }
    }
}
# Gets items based on the type Product
query GetItemsByType {
    product_All { # Root collection query specifies the content type
        items {
            price
        }
    }
}

Java
// Gets items of content type Product
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("system.type", "product")
    .build()
);
// Gets items of content type Product
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("system.type", "product")
    .build()
);

JavaScript
// Gets items based on the type Product
const response = await deliveryClient.items()
  .equalsFilter('system.type', 'product') // Same as using .type('product')
  .toPromise();
// Gets items based on the type Product
const response = await deliveryClient.items()
  .equalsFilter('system.type', 'product') // Same as using .type('product')
  .toPromise();

C#
// Gets items based on the type Product
IDeliveryItemListingResponse<Product> response = await deliveryClient.GetItemsAsync<Product>(
    new EqualsFilter("system.type", "product")
);
// Gets items based on the type Product
IDeliveryItemListingResponse<Product> response = await deliveryClient.GetItemsAsync<Product>(
    new EqualsFilter("system.type", "product")
);

PHP
// Gets items based on the type Product
$items = $deliveryClient->getItems((new QueryParams())
  ->equals('system.type', 'product'));
// Gets items based on the type Product
$items = $deliveryClient->getItems((new QueryParams())
  ->equals('system.type', 'product'));

cURL
# Gets items based on the type Product
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.type=product' \
  --header 'content-type: application/json'
# Gets items based on the type Product
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.type=product' \
  --header 'content-type: application/json'

Ruby
# Gets items of content type Product
delivery_client.items('system.type'.eq('product'))
# Gets items of content type Product
delivery_client.items('system.type'.eq('product'))

TypeScript
// Gets items based on the type Product
const response = await deliveryClient.items()
  .equalsFilter('system.type', 'product') // Same as using .type('product')
  .toPromise();
// Gets items based on the type Product
const response = await deliveryClient.items()
  .equalsFilter('system.type', 'product') // Same as using .type('product')
  .toPromise();

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

To get items based on multiple content types, specify multiple root collection queries.

GraphQL
# Gets items based on the types Product, Article, and News
query GetItemsByTypes {
    product_All { # Root collection query for Product means you'll get items based on the Product content type
        items {
            name
        }
    }
    article_All { # Root collection query for Article means you'll get items based on the Article content type
        items {
            title
        }
    }
    news_All { # Root collection query for News means you'll get items based on the News content type
        items {
            title
        }
    }
}
# Gets items based on the types Product, Article, and News
query GetItemsByTypes {
    product_All { # Root collection query for Product means you'll get items based on the Product content type
        items {
            name
        }
    }
    article_All { # Root collection query for Article means you'll get items based on the Article content type
        items {
            title
        }
    }
    news_All { # Root collection query for News means you'll get items based on the News content type
        items {
            title
        }
    }
}

Java
// Gets items based on the types Article, Product, and News
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterIn("system.type", "article", "product", "news")
    .build()
);
// Gets items based on the types Article, Product, and News
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterIn("system.type", "article", "product", "news")
    .build()
);

JavaScript
// Gets items based on the type Product, Article, and News
const response = await deliveryClient.items()
  .inFilter('system.type', ['product', 'article', 'news'])
  .toPromise();
// Gets items based on the type Product, Article, and News
const response = await deliveryClient.items()
  .inFilter('system.type', ['product', 'article', 'news'])
  .toPromise();

C#
// Gets items based on the types Product, Article, and News
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new InFilter("system.type", "product", "article", "news")
);
// Gets items based on the types Product, Article, and News
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new InFilter("system.type", "product", "article", "news")
);

PHP
// Gets items based on the types Product, Article, and News
$items = $deliveryClient->getItems((new QueryParams())
  ->in('system.type', ['product', 'article', 'news']));
// Gets items based on the types Product, Article, and News
$items = $deliveryClient->getItems((new QueryParams())
  ->in('system.type', ['product', 'article', 'news']));

cURL
# Gets items based on the types Product, Article, and News
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.type[in]=product,article,news' \
  --header 'content-type: application/json'
# Gets items based on the types Product, Article, and News
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.type[in]=product,article,news' \
  --header 'content-type: application/json'

Ruby
# Gets items based on the types Product, Article, and News
delivery_client.items('system.type'.in('product', 'article', 'news'))
# Gets items based on the types Product, Article, and News
delivery_client.items('system.type'.in('product', 'article', 'news'))

TypeScript
// Gets items based on the types Product, Article, and News
const response = await deliveryClient.items()
  .inFilter('system.type', ['product', 'article', 'news'])
  .toPromise();
// Gets items based on the types Product, Article, and News
const response = await deliveryClient.items()
  .inFilter('system.type', ['product', 'article', 'news'])
  .toPromise();

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.

GraphQL
# Gets articles modified after November 1 2021, 9 am UTC+0
query GetArticlesModifiedAfterDate {
  article_All (where: {_system_: {lastModified: {gt: "2021-11-01T09:00:00Z"}}}) {
    items {
      title
    }
  }
}

# Gets articles released at or after November 1 2021, 9 am UTC+0
query GetArticlesReleasedAfterDate {
  article_All (where: {releaseDate: {gte: "2021-11-01T09:00:00Z"}}) {
    items {
      title
    }
  }
}

# Gets articles modified before November 1 2021, 12 pm UTC+0. Last match would be at 2021-10-31T:11:59:59
query GetArticlesModifiedBeforeDate {
  article_All (where: {_system_: {lastModified: {lt: "2021-11-01T00:00:00Z"}}}) {
    items {
      title
    }
  } 
}

# Gets articles released at or before November 1 2021, 9 am UTC+0
query GetArticlesReleasedAfterDate {
  article_All (where: {releaseDate: {lte: "2021-11-01T09:00:00Z"}}) {
    items {
      title
    }
  }
}
# Gets articles modified after November 1 2021, 9 am UTC+0
query GetArticlesModifiedAfterDate {
  article_All (where: {_system_: {lastModified: {gt: "2021-11-01T09:00:00Z"}}}) {
    items {
      title
    }
  }
}

# Gets articles released at or after November 1 2021, 9 am UTC+0
query GetArticlesReleasedAfterDate {
  article_All (where: {releaseDate: {gte: "2021-11-01T09:00:00Z"}}) {
    items {
      title
    }
  }
}

# Gets articles modified before November 1 2021, 12 pm UTC+0. Last match would be at 2021-10-31T:11:59:59
query GetArticlesModifiedBeforeDate {
  article_All (where: {_system_: {lastModified: {lt: "2021-11-01T00:00:00Z"}}}) {
    items {
      title
    }
  } 
}

# Gets articles released at or before November 1 2021, 9 am UTC+0
query GetArticlesReleasedAfterDate {
  article_All (where: {releaseDate: {lte: "2021-11-01T09:00:00Z"}}) {
    items {
      title
    }
  }
}

Java
// 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 after April 9 2020, 9 am UTC+0
CompletionStage<ContentItemsListingResponse> items1 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterGreaterThan("system.last_modified", "2020-05-09T09:00:00.000000Z")
    .build()
);

// Gets items released at or after April 9 2020, 7 am UTC+0
CompletionStage<ContentItemsListingResponse> items2 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterGreaterThanEquals("system.release_date", "2020-05-09T07:00:00Z")
    .build()
);

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
CompletionStage<ContentItemsListingResponse> items3 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterLessThan("system.last_modified", "2020-05-05")
    .build()
);

// Gets items released at or before April 5 2020 10:30 am UTC+0
CompletionStage<ContentItemsListingResponse> items4 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterLessThanEquals("system.release_date", "2020-05-05T10:30:00Z")
    .build()
);
// 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 after April 9 2020, 9 am UTC+0
CompletionStage<ContentItemsListingResponse> items1 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterGreaterThan("system.last_modified", "2020-05-09T09:00:00.000000Z")
    .build()
);

// Gets items released at or after April 9 2020, 7 am UTC+0
CompletionStage<ContentItemsListingResponse> items2 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterGreaterThanEquals("system.release_date", "2020-05-09T07:00:00Z")
    .build()
);

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
CompletionStage<ContentItemsListingResponse> items3 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterLessThan("system.last_modified", "2020-05-05")
    .build()
);

// Gets items released at or before April 5 2020 10:30 am UTC+0
CompletionStage<ContentItemsListingResponse> items4 = client.getItems(
  DeliveryParameterBuilder.params()
    .filterLessThanEquals("system.release_date", "2020-05-05T10:30:00Z")
    .build()
);

JavaScript
// 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 after April 9 2020, 9 am UTC+0
const response = await deliveryClient.items()
  .greaterThanFilter('system.last_modified', '2020-05-09T09:00:00.000000Z')
  .toPromise();

// Gets items released at or after April 9 2020, 7 am UTC+0
const response = await deliveryClient.items()
  .greaterThanOrEqualFilter('elements.release_date', '2020-05-09T07:00:00Z')
  .toPromise();

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
const response = await deliveryClient.items()
  .lessThanFilter('system.last_modified', '2020-05-05')
  .toPromise();

// Gets items released at or before April 5 2020 10:30 am UTC+0
const response = await deliveryClient.items()
  .lessThanOrEqualFilter('elements.release_date', '2020-05-05T10:30:00Z')
  .toPromise();
// 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 after April 9 2020, 9 am UTC+0
const response = await deliveryClient.items()
  .greaterThanFilter('system.last_modified', '2020-05-09T09:00:00.000000Z')
  .toPromise();

// Gets items released at or after April 9 2020, 7 am UTC+0
const response = await deliveryClient.items()
  .greaterThanOrEqualFilter('elements.release_date', '2020-05-09T07:00:00Z')
  .toPromise();

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
const response = await deliveryClient.items()
  .lessThanFilter('system.last_modified', '2020-05-05')
  .toPromise();

// Gets items released at or before April 5 2020 10:30 am UTC+0
const response = await deliveryClient.items()
  .lessThanOrEqualFilter('elements.release_date', '2020-05-05T10:30:00Z')
  .toPromise();

C#
// 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 after April 9 2020, 9 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new GreaterThanFilter("system.last_modified", "2020-05-09T09:00:00.000000Z")
);

// Gets items released at or after April 9 2020, 7 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new GreaterThanOrEqualFilter("elements.release_date", "2020-05-09T07:00:00Z")
);

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new LessThanFilter("system.last_modified", "2020-05-05")
);

// Gets items released at or before April 5 2020 10:30 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new LessThanOrEqualFilter("elements.release_date", "2020-05-05T10:30:00Z")
);
// 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 after April 9 2020, 9 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new GreaterThanFilter("system.last_modified", "2020-05-09T09:00:00.000000Z")
);

// Gets items released at or after April 9 2020, 7 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new GreaterThanOrEqualFilter("elements.release_date", "2020-05-09T07:00:00Z")
);

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new LessThanFilter("system.last_modified", "2020-05-05")
);

// Gets items released at or before April 5 2020 10:30 am UTC+0
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new LessThanOrEqualFilter("elements.release_date", "2020-05-05T10:30:00Z")
);

PHP
// 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 after April 9 2020, 9 am UTC+0
$items1 = $client->getItems((new QueryParams())
  ->greaterThan('system.last_modified', '2020-05-09T09:00:00.000000Z'));

// Gets items released at or after April 9 2020, 7 am UTC+0
$items2 = $client->getItems((new QueryParams())
  ->greaterThanOrEqual('elements.release_date', '2020-05-09T07:00:00Z'));

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
$items3 = $client->getItems((new QueryParams())
  ->lessThan('system.last_modified', '2020-05-05'));

// Gets items released at or before April 5 2020 10:30 am UTC+0
$items4 = $client->getItems((new QueryParams())
  ->lessThanOrEqual('elements.release_date', '2020-05-05T10:30:00Z'));
// 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 after April 9 2020, 9 am UTC+0
$items1 = $client->getItems((new QueryParams())
  ->greaterThan('system.last_modified', '2020-05-09T09:00:00.000000Z'));

// Gets items released at or after April 9 2020, 7 am UTC+0
$items2 = $client->getItems((new QueryParams())
  ->greaterThanOrEqual('elements.release_date', '2020-05-09T07:00:00Z'));

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
$items3 = $client->getItems((new QueryParams())
  ->lessThan('system.last_modified', '2020-05-05'));

// Gets items released at or before April 5 2020 10:30 am UTC+0
$items4 = $client->getItems((new QueryParams())
  ->lessThanOrEqual('elements.release_date', '2020-05-05T10:30:00Z'));

cURL
# 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 after April 9 2020, 9 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[gt]=2020-05-09T09:00:00.000000Z' \
  --header 'content-type: application/json'

# Gets items released at or after April 9 2020, 7 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?"elements.release_date[gte]=2020-05-09T07:00:00Z"' \
  --header 'content-type: application/json'

# Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[lt]=2020-05-05' \
  --header 'content-type: application/json'

# Gets items released at or before April 5 2020 10:30 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.release_date", "2020-05-05T10:30:00Z' \
  --header 'content-type: application/json'
# 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 after April 9 2020, 9 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[gt]=2020-05-09T09:00:00.000000Z' \
  --header 'content-type: application/json'

# Gets items released at or after April 9 2020, 7 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?"elements.release_date[gte]=2020-05-09T07:00:00Z"' \
  --header 'content-type: application/json'

# Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[lt]=2020-05-05' \
  --header 'content-type: application/json'

# Gets items released at or before April 5 2020 10:30 am UTC+0
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.release_date", "2020-05-05T10:30:00Z' \
  --header 'content-type: application/json'

Ruby
# 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 after April 9 2020, 9 am UTC+0
delivery_client.items('system.last_modified'.greaterThan('2020-05-09T09:00:00.000000Z'))

# Gets items released at or after April 9 2020, 7 am UTC+0
delivery_client.items('elements.release_date'.greaterThanOrEqual('2020-05-09T07:00:00Z'))

# Gets items modified before April 5 2020 UTC+0; Last match would be at 2020-05-04T23:59:59
delivery_client.items('system.last_modified'.lessThan('2020-05-05'))

# Gets items released at or before April 5 2020 10:30 am UTC+0
delivery_client.items('elements.release_date'.lessThanOrEqual('2020-05-05T10:30:00Z'))
# 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 after April 9 2020, 9 am UTC+0
delivery_client.items('system.last_modified'.greaterThan('2020-05-09T09:00:00.000000Z'))

# Gets items released at or after April 9 2020, 7 am UTC+0
delivery_client.items('elements.release_date'.greaterThanOrEqual('2020-05-09T07:00:00Z'))

# Gets items modified before April 5 2020 UTC+0; Last match would be at 2020-05-04T23:59:59
delivery_client.items('system.last_modified'.lessThan('2020-05-05'))

# Gets items released at or before April 5 2020 10:30 am UTC+0
delivery_client.items('elements.release_date'.lessThanOrEqual('2020-05-05T10:30:00Z'))

TypeScript
// 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 after April 9 2020, 9 am UTC+0
const response = await deliveryClient.items()
  .greaterThanFilter('system.last_modified', '2020-05-09T09:00:00.000000Z')
  .toPromise();

// Gets items released at or after April 9 2020, 7 am UTC+0
const response = await deliveryClient.items()
  .greaterThanOrEqualFilter('elements.release_date', '2020-05-09T07:00:00Z')
  .toPromise();

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
const response = await deliveryClient.items()
  .lessThanFilter('system.last_modified', '2020-05-05')
  .toPromise();

// Gets items released at or before April 5 2020 10:30 am UTC+0
const response = await deliveryClient.items()
  .lessThanOrEqualFilter('elements.release_date', '2020-05-05T10:30:00Z')
  .toPromise();
// 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 after April 9 2020, 9 am UTC+0
const response = await deliveryClient.items()
  .greaterThanFilter('system.last_modified', '2020-05-09T09:00:00.000000Z')
  .toPromise();

// Gets items released at or after April 9 2020, 7 am UTC+0
const response = await deliveryClient.items()
  .greaterThanOrEqualFilter('elements.release_date', '2020-05-09T07:00:00Z')
  .toPromise();

// Gets items modified before April 5 2020 UTC+0. Last match would be at 2020-05-04T23:59:59.
const response = await deliveryClient.items()
  .lessThanFilter('system.last_modified', '2020-05-05')
  .toPromise();

// Gets items released at or before April 5 2020 10:30 am UTC+0
const response = await deliveryClient.items()
  .lessThanOrEqualFilter('elements.release_date', '2020-05-05T10:30:00Z')
  .toPromise();

Tip: Use the same approach for number elements.

Range of dates and numbers

The Delivery GraphQL API doesn't support filtering content items based on a range of values. See the list of supported filters.

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

Java
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterRange("system.last_modified", "2020-05-05T10:30:00", "2020-05-07T07:00:00")
    .build()
);
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterRange("system.last_modified", "2020-05-05T10:30:00", "2020-05-07T07:00:00")
    .build()
);

JavaScript
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
const response = await deliveryClient.items()
  .rangeFilter('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00')
  .toPromise();
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
const response = await deliveryClient.items()
  .rangeFilter('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00')
  .toPromise();

C#
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new RangeFilter("system.last_modified", "2020-05-05T10:30:00", "2020-05-07T07:00:00")
);
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new RangeFilter("system.last_modified", "2020-05-05T10:30:00", "2020-05-07T07:00:00")
);

PHP
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
$items = $client->getItems((new QueryParams())
  ->range('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00'));
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
$items = $client->getItems((new QueryParams())
  ->range('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00'));

cURL
# 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[range]=2020-05-05T10:30:00,2020-05-07T07:00:00' \
  --header 'content-type: application/json'
# 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?system.last_modified[range]=2020-05-05T10:30:00,2020-05-07T07:00:00' \
  --header 'content-type: application/json'

Ruby
# 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
delivery_client.items('system.last_modified'.range('2020-05-05T10:30:00','2020-05-07T07:00:00'))
# 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
delivery_client.items('system.last_modified'.range('2020-05-05T10:30:00','2020-05-07T07:00:00'))

TypeScript
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
const response = await deliveryClient.items()
  .rangeFilter('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00')
  .toPromise();
// 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 April 5, 2020 10:30 UTC and April 7, 2020, 7:00 UTC
const response = await deliveryClient.items()
  .rangeFilter('system.last_modified', '2020-05-05T10:30:00', '2020-05-07T07:00:00')
  .toPromise();

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.

Java
// Gets items whose rating is at least 6.5 and at most 9
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterRange("elements.product_rating", "6.5", "9")
    .build()
);
// Gets items whose rating is at least 6.5 and at most 9
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterRange("elements.product_rating", "6.5", "9")
    .build()
);

JavaScript
// Gets items whose rating is at least 6.5 and at most 9
const response = await deliveryClient.items()
  .rangeFilter('elements.product_rating', '6.5', '9')
  .toPromise();
// Gets items whose rating is at least 6.5 and at most 9
const response = await deliveryClient.items()
  .rangeFilter('elements.product_rating', '6.5', '9')
  .toPromise();

C#
// Gets items whose rating is at least 6.5 and at most 9
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new RangeFilter("elements.product_rating", "6.5", "9")
);
// Gets items whose rating is at least 6.5 and at most 9
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new RangeFilter("elements.product_rating", "6.5", "9")
);

PHP
// Gets items whose rating is at least 6.5 and at most 9
$items = $client->getItems((new QueryParams())
  ->range('elements.product_rating', '6.5', '9'));
// Gets items whose rating is at least 6.5 and at most 9
$items = $client->getItems((new QueryParams())
  ->range('elements.product_rating', '6.5', '9'));

cURL
# Gets items whose rating is at least 6.5 and at most 9
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.product_rating[range]=6.5,9' \
  --header 'content-type: application/json'
# Gets items whose rating is at least 6.5 and at most 9
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.product_rating[range]=6.5,9' \
  --header 'content-type: application/json'

Ruby
# Gets items whose rating is at least 6.5 and at most 9
delivery_client.items('elements.product_rating'.range('7', '9'))
# Gets items whose rating is at least 6.5 and at most 9
delivery_client.items('elements.product_rating'.range('7', '9'))

TypeScript
// Gets items whose rating is at least 6.5 and at most 9
const response = await deliveryClient.items()
  .rangeFilter('elements.product_rating', '6.5', '9')
  .toPromise();
// Gets items whose rating is at least 6.5 and at most 9
const response = await deliveryClient.items()
  .rangeFilter('elements.product_rating', '6.5', '9')
  .toPromise();

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.

GraphQL
# Gets articles whose Title element value equals to "Hello World"
query GetArticleByTitle {
  article_All(where: {title: {eq: "Hello World"}}) {
    items {
      title
    }
  }
}
# Gets articles whose Title element value equals to "Hello World"
query GetArticleByTitle {
  article_All(where: {title: {eq: "Hello World"}}) {
    items {
      title
    }
  }
}

Java
// Gets items whose Title element value equals to "Hello World"
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("elements.title", "Hello World")
    .build()
);
// Gets items whose Title element value equals to "Hello World"
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("elements.title", "Hello World")
    .build()
);

JavaScript
// Gets items whose Title element value equals to "Hello World"
const response = await deliveryClient.items()
  .equalsFilter('elements.title', 'Hello World')
  .toPromise();
// Gets items whose Title element value equals to "Hello World"
const response = await deliveryClient.items()
  .equalsFilter('elements.title', 'Hello World')
  .toPromise();

C#
// Gets items whose Title element value equals to "Hello World" 
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("elements.title", "Hello World")
);
// Gets items whose Title element value equals to "Hello World" 
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("elements.title", "Hello World")
);

PHP
// Gets items whose Title element value equals to 'Hello World'
$items = $client->getItems((new QueryParams())
  ->equals('elements.title', 'Hello World'));
// Gets items whose Title element value equals to 'Hello World'
$items = $client->getItems((new QueryParams())
  ->equals('elements.title', 'Hello World'));

cURL
# Gets items whose Title element value equals to "Hello World"
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.title=Hello World' \
  --header 'content-type: application/json'
# Gets items whose Title element value equals to "Hello World"
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.title=Hello World' \
  --header 'content-type: application/json'

Ruby
# Gets items whose Title element value equals to "Hello World"
delivery_client.items('elements.title'.eq('Hello World'))
# Gets items whose Title element value equals to "Hello World"
delivery_client.items('elements.title'.eq('Hello World'))

TypeScript
// Gets items whose Title element value equals to 'Hello World'
const response = await deliveryClient.items()
  .equalsFilter('elements.title', 'Hello World')
  .toPromise();
// Gets items whose Title element value equals to 'Hello World'
const response = await deliveryClient.items()
  .equalsFilter('elements.title', 'Hello World')
  .toPromise();

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.

To get items tagged with specific taxonomy terms, you need to specify the terms using either the containsAny or containsAll filters.

GraphQL
# Note: Filters work with codenames. This means codenames of the taxonomy terms or multiple choice options.
# Gets items tagged with one specific tag
query GetArticlesTaggedWithATerm {
  article_All(where: {topic: {containsAny: ["kontent_ai"]}}) {
    items {
      title
    }
  }
}

# Gets items tagged with a list of specific tags
query GetArticlesTaggedWithTerms {
  article_All(where: {topic: {containsAll: ["kontent_ai", "cms"]}}) {
    items {
      title
    }
  }
}

# Gets items tagged with at least one tag from the list
query GetArticlesTaggedWithOneOfTerms {
  article_All(where: {topic: {containsAny: ["headless", "cms"]}}) {
    items {
      title
    }
  }
}
# Note: Filters work with codenames. This means codenames of the taxonomy terms or multiple choice options.
# Gets items tagged with one specific tag
query GetArticlesTaggedWithATerm {
  article_All(where: {topic: {containsAny: ["kontent_ai"]}}) {
    items {
      title
    }
  }
}

# Gets items tagged with a list of specific tags
query GetArticlesTaggedWithTerms {
  article_All(where: {topic: {containsAll: ["kontent_ai", "cms"]}}) {
    items {
      title
    }
  }
}

# Gets items tagged with at least one tag from the list
query GetArticlesTaggedWithOneOfTerms {
  article_All(where: {topic: {containsAny: ["headless", "cms"]}}) {
    items {
      title
    }
  }
}

Java
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.tags", "kontent_ai")
    .build()
);

// Gets items tagged with a list of specific tags
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAll("elements.tags", "kontent_ai", "cms")
    .build()
);

// Gets items tagged with at least one of multiple tags
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.tags", "headless", "cms")
    .build()
);
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.tags", "kontent_ai")
    .build()
);

// Gets items tagged with a list of specific tags
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAll("elements.tags", "kontent_ai", "cms")
    .build()
);

// Gets items tagged with at least one of multiple tags
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.tags", "headless", "cms")
    .build()
);

JavaScript
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
const response = await deliveryClient.items()
  .containsFilter('elements.tags', ['kontent_ai'])
  .toPromise();

// Gets items tagged with a list of specific tags
const response = await deliveryClient.items()
  .allFilter('elements.tags', ['kontent_ai', 'cms'])
  .toPromise();

// Gets items tagged with at least one tag from the list
const response = await deliveryClient.items()
  .anyFilter('elements.tags', ['headless', 'cms'])
  .toPromise();
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
const response = await deliveryClient.items()
  .containsFilter('elements.tags', ['kontent_ai'])
  .toPromise();

// Gets items tagged with a list of specific tags
const response = await deliveryClient.items()
  .allFilter('elements.tags', ['kontent_ai', 'cms'])
  .toPromise();

// Gets items tagged with at least one tag from the list
const response = await deliveryClient.items()
  .anyFilter('elements.tags', ['headless', 'cms'])
  .toPromise();

C#
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new ContainsFilter("elements.tags", "kontent_ai")
);

// Gets items tagged with a list of specific tags
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AllFilter("elements.tags", "kontent_ai", "cms")
);

// Gets items tagged with at least one tag from the list
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AnyFilter("elements.tags", "headless", "cms")
);
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new ContainsFilter("elements.tags", "kontent_ai")
);

// Gets items tagged with a list of specific tags
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AllFilter("elements.tags", "kontent_ai", "cms")
);

// Gets items tagged with at least one tag from the list
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AnyFilter("elements.tags", "headless", "cms")
);

PHP
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
$items = $client->getItems((new QueryParams())
  ->contains('elements.tags', ['kontent_ai']));

// Gets items tagged with a list of specific tags
$items = $client->getItems((new QueryParams())
  ->all('elements.tags', ['kontent_ai','cms']));

// Gets items tagged with at least one of multiple tags
$items = $client->getItems((new QueryParams())
  ->any('elements.tags', ['headless','cms']));
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
$items = $client->getItems((new QueryParams())
  ->contains('elements.tags', ['kontent_ai']));

// Gets items tagged with a list of specific tags
$items = $client->getItems((new QueryParams())
  ->all('elements.tags', ['kontent_ai','cms']));

// Gets items tagged with at least one of multiple tags
$items = $client->getItems((new QueryParams())
  ->any('elements.tags', ['headless','cms']));

cURL
# Note: Filters work with codenames of the tags.
# Gets items tagged with one specific tag
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[contains]=kontent_ai' \
  --header 'content-type: application/json'
  
# Gets items tagged with a list of specific tags
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[all]=kontent_ai,cms' \
  --header 'content-type: application/json'

# Gets items tagged with at least one of multiple tags
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[any]=headless,cms' \
  --header 'content-type: application/json'
# Note: Filters work with codenames of the tags.
# Gets items tagged with one specific tag
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[contains]=kontent_ai' \
  --header 'content-type: application/json'
  
# Gets items tagged with a list of specific tags
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[all]=kontent_ai,cms' \
  --header 'content-type: application/json'

# Gets items tagged with at least one of multiple tags
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.tags[any]=headless,cms' \
  --header 'content-type: application/json'

Ruby
# Note: Filters work with codenames of the tags.
# Gets itmes tagged with one specific tag
delivery_client.items('elements.tags'.contains('kontent_ai'))

# Gets items tagged with a list of specific tags
delivery_client.items('elements.tags'.any('kontent_ai', 'cms'))

# Gets items tagged with at least one of multiple tags
delivery_client.items('elements.tags'.contains('headless', 'cms'))
# Note: Filters work with codenames of the tags.
# Gets itmes tagged with one specific tag
delivery_client.items('elements.tags'.contains('kontent_ai'))

# Gets items tagged with a list of specific tags
delivery_client.items('elements.tags'.any('kontent_ai', 'cms'))

# Gets items tagged with at least one of multiple tags
delivery_client.items('elements.tags'.contains('headless', 'cms'))

TypeScript
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
const response = await deliveryClient.items()
  .containsFilter('elements.tags', ['kontent_ai'])
  .toPromise();

// Gets items tagged with a list of specific tags
const response = await deliveryClient.items()
  .allFilter('elements.tags', ['kontent_ai', 'cms'])
  .toPromise();

// Gets items tagged with at least one tag from the list
const response = await deliveryClient.items()
  .anyFilter('elements.tags', ['headless', 'cms'])
  .toPromise();
// Note: Filters work with codenames of the tags.
// Gets items tagged with one specific tag
const response = await deliveryClient.items()
  .containsFilter('elements.tags', ['kontent_ai'])
  .toPromise();

// Gets items tagged with a list of specific tags
const response = await deliveryClient.items()
  .allFilter('elements.tags', ['kontent_ai', 'cms'])
  .toPromise();

// Gets items tagged with at least one tag from the list
const response = await deliveryClient.items()
  .anyFilter('elements.tags', ['headless', 'cms'])
  .toPromise();

Also works for multiple choice and custom elements

Use the same approach to get items based on a specific value or values of 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\"]".

Also works for multiple choice elements

Use the same approach to get items based on a specific value or values of multiple choice elements.

URL slug

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

GraphQL
# Gets items whose URL slug equals to sample-url-slug
query GetArticlesByUrlSlug {
  article_All(where: {url: {eq: "sample-url-slug"}}) {
    items {
      title
    }
  }
}
# Gets items whose URL slug equals to sample-url-slug
query GetArticlesByUrlSlug {
  article_All(where: {url: {eq: "sample-url-slug"}}) {
    items {
      title
    }
  }
}

Java
// Gets items whose URL slug equals to sample-url-slug
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("elements.url_slug", "sample-url-slug")
    .build()
);
// Gets items whose URL slug equals to sample-url-slug
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterEquals("elements.url_slug", "sample-url-slug")
    .build()
);

JavaScript
// Gets items whose URL slug equals to sample-url-slug
const response = await deliveryClient.items()
  .equalsFilter('elements.url_slug', 'sample-url-slug')
  .toPromise();
// Gets items whose URL slug equals to sample-url-slug
const response = await deliveryClient.items()
  .equalsFilter('elements.url_slug', 'sample-url-slug')
  .toPromise();

C#
// Gets items whose URL slug equals to sample-url-slug
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("elements.url_slug", "sample-url-slug")
);
// Gets items whose URL slug equals to sample-url-slug
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new EqualsFilter("elements.url_slug", "sample-url-slug")
);

PHP
// Gets items whose URL slug equals to sample-url-slug
$items = $client->getItems((new QueryParams())
  ->equals('elements.url_slug', 'sample-url-slug'));
// Gets items whose URL slug equals to sample-url-slug
$items = $client->getItems((new QueryParams())
  ->equals('elements.url_slug', 'sample-url-slug'));

cURL
# Gets items whose URL slug equals to sample-url-slug
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.url_slug=sample-url-slug' \
  --header 'content-type: application/json'
# Gets items whose URL slug equals to sample-url-slug
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.url_slug=sample-url-slug' \
  --header 'content-type: application/json'

Ruby
# Gets items whose URL slug equals to sample-url-slug
delivery_client.items('elements.url_slug'.eq('sample-url-slug'))
# Gets items whose URL slug equals to sample-url-slug
delivery_client.items('elements.url_slug'.eq('sample-url-slug'))

TypeScript
// Gets items whose URL slug equals to sample-url-slug
const response = await deliveryClient.items()
  .equalsFilter('elements.url_slug', 'sample-url-slug')
  .toPromise();
// Gets items whose URL slug equals to sample-url-slug
const response = await deliveryClient.items()
  .equalsFilter('elements.url_slug', 'sample-url-slug')
  .toPromise();

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

Author of an article and other relationships

When you link multiple items together you might want to retrieve your items based on their relationships.

For example, you can have several articles written by a single author, Jane. Each article has a linked items element named Author. This element contains a reference to a content item that represents the author Jane. The reference in the Author element is stored as a codename of the Jane content item.

GraphQL
# Gets items attributed to Jane.
query GetArticlesByAuthor {
  article_All(where: {author: {containsAll: ["jane_doe"]}}) {
    items {
      title
    }
  }
}

# Gets items attributed to at least Jane, John, or both.
query GetArticlesByOneOfAuthors {
  article_All(where: {author: {containsAny: ["jane_doe", "john_wick"]}}) {
    items {
      title
    }
  }
}
# Gets items attributed to Jane.
query GetArticlesByAuthor {
  article_All(where: {author: {containsAll: ["jane_doe"]}}) {
    items {
      title
    }
  }
}

# Gets items attributed to at least Jane, John, or both.
query GetArticlesByOneOfAuthors {
  article_All(where: {author: {containsAny: ["jane_doe", "john_wick"]}}) {
    items {
      title
    }
  }
}

Java
// Gets items attributed to Jane.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.author", "jane_doe")
    .build()
);


// Gets items attributed to at least Jane, John, or both.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.author", "jane_doe", "john_wick")
    .build()
);
// Gets items attributed to Jane.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.author", "jane_doe")
    .build()
);


// Gets items attributed to at least Jane, John, or both.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.author", "jane_doe", "john_wick")
    .build()
);

JavaScript
// Gets items attributed to Jane.
const response = await deliveryClient.items()
  .containsFilter('elements.author', ['jane_doe'])
  .toPromise();

// Gets items attributed to at least Jane, John, or both.
const response = await deliveryClient.items()
  .anyFilter('elements.author', ['jane_doe', 'john_wick'])
  .toPromise();
// Gets items attributed to Jane.
const response = await deliveryClient.items()
  .containsFilter('elements.author', ['jane_doe'])
  .toPromise();

// Gets items attributed to at least Jane, John, or both.
const response = await deliveryClient.items()
  .anyFilter('elements.author', ['jane_doe', 'john_wick'])
  .toPromise();

C#
// Gets items attributed to Jane.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new ContainsFilter("elements.author", "jane_doe")
);

// Gets items attributed to at least Jane, John, or both.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AnyFilter("elements.author", "jane_doe", "john_wick")
);
// Gets items attributed to Jane.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new ContainsFilter("elements.author", "jane_doe")
);

// Gets items attributed to at least Jane, John, or both.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
    new AnyFilter("elements.author", "jane_doe", "john_wick")
);

PHP
// Gets items attributed to Jane.
$items = $client->getItems((new QueryParams())
  ->contains('elements.author', 'jane_doe'));

// Gets items attributed to at least Jane, John, or both.
$items = $client->getItems((new QueryParams())
  ->any('elements.author', ['jane_doe','john_wick']));
// Gets items attributed to Jane.
$items = $client->getItems((new QueryParams())
  ->contains('elements.author', 'jane_doe'));

// Gets items attributed to at least Jane, John, or both.
$items = $client->getItems((new QueryParams())
  ->any('elements.author', ['jane_doe','john_wick']));

cURL
# Gets items attributed to Jane.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.author[contains]=jane_doe' \
  --header 'content-type: application/json'

# Gets items attributed to at least Jane, John, or both.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.author[any]=jane_doe,john_wick' \
  --header 'content-type: application/json'
# Gets items attributed to Jane.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.author[contains]=jane_doe' \
  --header 'content-type: application/json'

# Gets items attributed to at least Jane, John, or both.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.author[any]=jane_doe,john_wick' \
  --header 'content-type: application/json'

Ruby
# Gets items attributed to Jane.
delivery_client.items('elements.author'.contains('jane_doe'))

# Gets items attributed to at least Jane, John, or both.
delivery_client.items('elements.author'.any('jane_doe', 'john_wick'))
# Gets items attributed to Jane.
delivery_client.items('elements.author'.contains('jane_doe'))

# Gets items attributed to at least Jane, John, or both.
delivery_client.items('elements.author'.any('jane_doe', 'john_wick'))

TypeScript
// Gets items attributed to Jane.
const response = await deliveryClient.items()
  .containsFilter('elements.author', ['jane_doe'])
  .toPromise();

// Gets items attributed to at least Jane, John, or both.
const response = await deliveryClient.items()  
  .anyFilter('elements.author', ['jane_doe', 'john_wick'])
  .toPromise();
// Gets items attributed to Jane.
const response = await deliveryClient.items()
  .containsFilter('elements.author', ['jane_doe'])
  .toPromise();

// Gets items attributed to at least Jane, John, or both.
const response = await deliveryClient.items()  
  .anyFilter('elements.author', ['jane_doe', 'john_wick'])
  .toPromise();

Subpages

When using Web Spotlight to manage your website content, 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.

GraphQL
# Gets pages linking travel insurance as their subpage.
query GetArticlesTaggedWithATerm {
  article_All(where: {subpages: {containsAll: ["travel_insurance"]}}) {
    items {
      title
    }
  }
}

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
query GetArticlesTaggedWithTerms {
  article_All(where: {subpages: {containsAny: ["travel_insurance", "car_insurance"]}}) {
    items {
      title
    }
  }
}
# Gets pages linking travel insurance as their subpage.
query GetArticlesTaggedWithATerm {
  article_All(where: {subpages: {containsAll: ["travel_insurance"]}}) {
    items {
      title
    }
  }
}

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
query GetArticlesTaggedWithTerms {
  article_All(where: {subpages: {containsAny: ["travel_insurance", "car_insurance"]}}) {
    items {
      title
    }
  }
}

Java
// Gets pages linking travel insurance as their subpage.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.subpages", "travel_insurance")
    .build()
);

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.subpages", "travel_insurance", "car_insurance")
    .build()
);
// Gets pages linking travel insurance as their subpage.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterContains("elements.subpages", "travel_insurance")
    .build()
);

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
CompletionStage<ContentItemsListingResponse> items = client.getItems(
  DeliveryParameterBuilder.params()
    .filterAny("elements.subpages", "travel_insurance", "car_insurance")
    .build()
);

JavaScript
// Gets pages linking travel insurance as their subpage.
const response = await deliveryClient.items()
  .containsFilter('elements.subpages', ['travel_insurance'])
  .toPromise();

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
const response = await deliveryClient.items()
  .anyFilter('elements.subpages', ['travel_insurance', 'car_insurance'])
  .toPromise();
// Gets pages linking travel insurance as their subpage.
const response = await deliveryClient.items()
  .containsFilter('elements.subpages', ['travel_insurance'])
  .toPromise();

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
const response = await deliveryClient.items()
  .anyFilter('elements.subpages', ['travel_insurance', 'car_insurance'])
  .toPromise();

C#
// Gets pages linking travel insurance as their subpage.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new ContainsFilter("elements.subpages", "travel_insurance")
);

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new AnyFilter("elements.subpages", "travel_insurance", "car_insurance")
);
// Gets pages linking travel insurance as their subpage.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new ContainsFilter("elements.subpages", "travel_insurance")
);

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
IDeliveryItemListingResponse<object> response = await deliveryClient.GetItemsAsync<object>(
  new AnyFilter("elements.subpages", "travel_insurance", "car_insurance")
);

PHP
// Gets pages linking travel insurance as their subpage.
$items = $client->getItems((new QueryParams())
  ->contains('elements.subpages', 'travel_insurance'));

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
$items = $client->getItems((new QueryParams())
  ->any('elements.subpages', ['travel_insurance','car_insurance']));
// Gets pages linking travel insurance as their subpage.
$items = $client->getItems((new QueryParams())
  ->contains('elements.subpages', 'travel_insurance'));

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
$items = $client->getItems((new QueryParams())
  ->any('elements.subpages', ['travel_insurance','car_insurance']));

cURL
# Gets pages linking travel insurance as their subpage.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.subpages[contains]=travel_insurance' \
  --header 'content-type: application/json'

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.subpages[any]=travel_insurance,car_insurance' \
  --header 'content-type: application/json'
# Gets pages linking travel insurance as their subpage.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.subpages[contains]=travel_insurance' \
  --header 'content-type: application/json'

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
curl --request GET \
  --url 'https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/items?elements.subpages[any]=travel_insurance,car_insurance' \
  --header 'content-type: application/json'

Ruby
# Gets pages linking travel insurance as their subpage.
delivery_client.items('elements.subpages'.contains('travel_insurance'))

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
delivery_client.items('elements.subpages'.any('travel_insurance', 'car_insurance'))
# Gets pages linking travel insurance as their subpage.
delivery_client.items('elements.subpages'.contains('travel_insurance'))

# Gets pages linking at least travel insurance, car insurance, or both as their subpage.
delivery_client.items('elements.subpages'.any('travel_insurance', 'car_insurance'))

TypeScript
// Gets pages linking travel insurance as their subpage.
const response = await deliveryClient.items()
  .containsFilter('elements.subpages', ['travel_insurance'])
  .toPromise();

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
const response = await deliveryClient.items()
  .anyFilter('elements.subpages', ['travel_insurance', 'car_insurance'])
  .toPromise();
// Gets pages linking travel insurance as their subpage.
const response = await deliveryClient.items()
  .containsFilter('elements.subpages', ['travel_insurance'])
  .toPromise();

// Gets pages linking at least travel insurance, car insurance, or both as their subpage.
const response = await deliveryClient.items()
  .anyFilter('elements.subpages', ['travel_insurance', 'car_insurance'])
  .toPromise();

What's next?

Build your app on solid foundations and best practices on getting content.
When you get the right items, it's time to resolve and render your content.
Take a deep dive into API reference with the Delivery REST API filters and Delivery GraphQL API filters.

Is this page helpful?

Yes No

Filter content items (examples)

Table of contents

Item ID or codename

Content types

Date & time and numbers

Range of dates and numbers

Text and rich text

Taxonomy and multiple choice

URL slug

Author of an article and other relationships

Subpages

What's next?

Is this page helpful?