> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. You can use a variety of query parameters to search and filter items in the response from any collection endpoint including entries, content types and assets. ## Content type To search for entries with a specific content type, set the `content_type` URI query parameter to the ID you want to search for. **Note**: When querying entries and using search filters based on `fields` or ordering by `fields` you must specify this parameter. You can only specify one value for `content_type` at a time. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M ``` `content_type` is a string representing the alphanumeric id of the content type to retrieve. This example finds all entries of content type 'Product'. ## Select operator The select operator allows you to choose what fields to return from an entity. You can choose multiple values by combining comma separated operators. For example, if you want to return the `sys.id` and `fields.name` of an Entry you would use: ``` /spaces/yadj1kx9rmg0/environments/staging/entries/?select=sys.id,fields.productName&content_type=2PqfXUJwE8qSYKuM0U6w8M ``` You can fetch the entire `sys` or `fields` object and it's sub-fields by passing it to the `select` operator. For example to omit the `sys` object: ``` /spaces/yadj1kx9rmg0/environments/staging/entries/?select=fields&content_type=2PqfXUJwE8qSYKuM0U6w8M ``` The select operator has some restrictions: * It is only applicable for collections of Entries and Assets, and with an Entry you must provide the `content_type` query parameter. * It can only select properties to a depth of **2**. For example, `select=fields.productName.en-US` is not valid. * If you want to select a property for a specific locale, you need to combine the `select` and `locale` operators, e.g `/assets/?select=fields.productName&locale=en-US`. * You can select up to 100 properties. * If you use the select operator on an Entry with linked fields, only the content linked to a field you select will be returned. If you provide an invalid property path, e.g `fields.doesNotExist`, Contentful returns a `400 Bad request` containing the invalid property path. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&select=fields.productName ``` To select only the `productName` field of each entry. ## Equality operator You can search for exact matches by using the equality operator. This includes querying an entry by an ID value instead of retrieving the Entry directly, which allows you to include resolved links. **Note**: Equality and inequality operators are not supported for text fields and you need to constrain search queries for fields with a `content_type` URI query parameter. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sys.id=5KsDBWseXY6QegucYAoacS ``` To find all entries with the ID `` (IDs are unique). ## Inequality operator Uses the `[ne]` parameter to exclude items matching a certain pattern. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sys.id[ne]=5KsDBWseXY6QegucYAoacS ``` To return all entries, except those with the ID ``. ## Array equality/inequality The equality/inequality operators also work with array fields: * **Equality**: If one of the items in an array matches the searched term, then it returns the entry. * **Inequality**: If one of the fields in an array matches the searched term, then the entry is **not** returned. **Note**: As the query filters by a field, you need to specify a content type. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.tags=accessories ``` This example finds all products tagged as `accessories` by matching `fields.tags` (an array) against a single value. ## Array with multiple values It's possible to use the `[all]` operator to retrieve entries matching a specific set of values (e.g. `fields.likes[all]=flowers,accessories`) Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.tags[all]=flowers,accessories ``` To find all products tagged as `flowers` and `accessories` by using the `all` operator with `fields.tags` (an array) and the two values. ## Inclusion You can filter a field by multiple values with the `[in]` operator. When applied to an array value there must be at least one matching item. Similarly, when including a field value, you need to specify a Content type. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.tags[in]=accessories,flowers ``` To retrieve entries that match `accessories` and `flowers`. ## Exclusion You can filter a field by multiple values with the `[nin]` operator. When applied to an array value there must be at least one not matching item. Similarly, when including a field value, you need to specify a content type. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.tags[nin]=flowers,accessories ``` To retrieve all products tagged as neither 'flowers' nor 'accessories'. ## Existence You can check for the presence of a field using the `[exists]` operator. It checks whether a certain field is defined (i.e. it has any value) or not. If the field is not defined, it will not be present in the JSON payload and the operator will consider it non-existent. You can pass `true` or `false` as a parameter depending on if you want to retrieve entries where the field exists (`true`) or does not exist (`false`). Please note that the parameter is case sensitive, `True` or `False` are not valid values. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.tags[exists]=true ``` To retrieve all entries that have a value for `field.tags` defined. ## Ranges Four range operators are available that you can apply to date and number fields: * `[lt]`: Less than. * `[lte]`: Less than or equal to. * `[gt]`: Greater than. * `[gte]`: Greater than or equal to. When applied to field values, you must specify the content type in the query. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sys.updatedAt[gte]=2013-01-01T00:00:00Z ``` To retrieve entries updated since midnight of January 1st 2013. ## Full-text search You have available two flavours of full-text search: * Global, described in this section * Field scoped, described in the section [full-text search on a field](#full-text-search-on-a-field) ### How does global full text search work There are cases where you want to find all the content resources which contain some particular words (search terms) but you don't know from which content type (for entries) or on which field those terms can be, so you can't use any of the field filters. For cases like these full-text search is the perfect tool for the job. With it you can find all the content resources which match your search terms in any of their text and symbol fields. Full-text search can be used to find entries, assets or content types. For the remainder of this section we will refer to entries but the same principles and restrictions will apply to the other types. #### Which content is looked up during a global full-text search? All text (both regular and rich text) and symbol fields in all the locales in your environment will be looked up when doing a global full-text search. #### How is an entry considered a match? Before we explain how we identify matches to your search terms we have to explain how these terms are transformed before they are sent to the search engine. After the API has received your query, the input string is sanitized (i.e. some special characters are removed), tokenized (i.e. split into its constituent parts), and normalized (i.e. the tokens are guaranteed to satisfy certain constrains, e.g. removing XML tags). Then each of the remaining search tokens is suffixed with a wildcard operator, which implies that full-text search at contentful is left-anchored. When checking if an entry satisfies the search criteria, the search engine tests if all of the search tokens (i.e. the transformed search terms) can be found in any field in any locale in the entry. This means that an entry can be included in the result set due to matches in different fields and different locales or due to a match in just one field in just one locale. There is also no guarantee about the order in which the search terms can appear in the matching entries. A search for *modern red house* can be matched with entries which have those words in any possible order (e.g. *red ... house ... modern*, *red ... modern ... house*, etc.). All this combined means that when you for example search for *my cat is blue*, the search engine will find all the entries where there are words starting with *my* and *cat* and *is* and *blue*: * A field with content like *my cat is blue* will match. * A field with content like *my cat is red* will not match. * A field with content like *there is a catastrophic blueberries accident in my town* will match. * A field with content like *there is a caterpillar in my house* will not match. * A field with content like *this is a picture of a caterpillar and myself wearing a bluejacket* will match. * A field with content like *my cat is \blue\* will match. * A field with content like *my cat is \great\* will not match. * An entry with a field with content like *my house was blue* and another field with content like *there is a cat* will match. Check below the phrase full-text search section if you are interested on those entries where the given search terms can only be found in one field and in the same order as in the search input. Check the [full-text search on a field](#full-text-search-on-a-field) section if you are interested only on those entries where the given search terms are in only one field. ### Phrase full-text search By default full-text search queries will take the search tokens and find all those entries where the tokens can be found in any field, in any locale and in any order. There are however cases where you might need a more restrictive search strategy and only get those entries where the matches are in the same order as you specified in the search and in only one field. To achieve this you can wrap the search terms in double quotes (") to enable phrase search. When you for example search for *"my cat is blue"*, the search engine will find all the entries where the words *my*, *cat*, *is* and *blue* are found in that order in one field: * A field with content like *my cat is blue* will match. * A field with content like *my cat is \blue\* will match. * A field with content like *blue is the color of my cat* will not match. * A field with content like *my caterpillar is blue* will not match. * An entry with a field with content like *my house was blue* and another field with content like *there is a cat* will not match. If you wish you can combine phrase search with the default full-text search behaviour. This can be useful to refine even more the result set. For example a search like *"my cat is blue" summer london* will match all those entries where the term *"my cat is blue"* can be found in just one field in one locale and where the terms *summer* and *london* can be found in any field in any locale present in the entry (including the field where the phrase was matched). ### Other considerations about full-text search * Full-text search is case insensitive and might return more results than expected. * A query will ignore search tokens with less than **2** characters. * When using full text search, make your search terms as specific as possible. * The `[match]` operator might return better results. * Use phrase search when possible as it has better performance. * For performance reasons it is recommended to use the [equality search operator](#equality-operator) when searching for slugs or text IDs. For more tips on using full-text search, see our [Help Center article](https://www.contentful.com/help/content-search/#tips-for-optimizing-search). Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&query=design ``` To retrieve all entries containing the word 'design'. ## Full-text search on a field With the `[match]` operator you can do a full-text search restricted to the content of a specific field. The way full-text search behaves on one field is the same as in the global full-text search and the documentation for the [global full-text search](#full-text-search) also applies here, with the particularity that matches on other fields of the entries or assets won't be considered. As with the global search, you can enabled phrase search if you wrap the input search terms in double quoutes ("). Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=sFzTZbSuM8coEwygeUYes&fields.website[match]=content ``` To retrieve all entries which contain words starting with 'content' in the 'website' field. ## Location proximity search You can use a proximity search on location-enabled content to find results in a specified geographical area. **Note**: Queries that include exact coordinates can't take advantage of our caching layer. With many use cases it should be enough to round the coordinates to 3 decimal places (an accuracy of about 300m), 2 decimal places (an accuracy of about 1km) or more to improve your cache hit rates. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&fields.center[near]=38,-122&content_type=city ``` A common use case for location search is to search for places close to the user's current position. Use the `[near]` operator to show results closest to a specific map location and order the results by distance. This will return all entries sorted by distance from the point at `latitude=38` and `longitude=-122`. ## Locations in a bounding object When displaying content on a map it's more resource efficient to retrieve only content that is in the current visible map area. For these cases, use the `within` operator. Similar to the 'near me' use case, this lets you search for locations that are within the specific area on the map and can be useful for finding related entries in the vicinity of another entry. There are two ways to search for nearby locations. #### 1. Using a bounding rectangle: To search for locations within a rectangle area object, use the structure `field.center[within]=latitude1,longitude1,latitude2,longitude2`, where: * `latitude1` and `longitude1` refer to the coordinates of the bottom left corner of the rectangle. * `latitude2` and `longitude2` refer to the coordinates of the top right corner of the rectangle. #### 2. Using a bounding circle: The structure `field.center[within]=latitude,longitude,radius` will return entries included in the circle with `fields.center` of the given latitude, longitude and radius (in km). Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&fields.center[within]=40,-124,36,-121&content_type=city ``` To retrieve entries where `fields.center` is within the rectangle with: * **Bottom left corner**: latitude 1, longitude 2. * **Top right corner**: latitude 3, longitude 4. ## Links to entry To search for entries which have a field linking to a specific entry, set the `links_to_entry` URI query parameter to the ID you want to search for. **NOTE: For most use cases it is more performant to query based on a content type's reference field if the desired content type is known. See [Search on references](#search-on-references) for an example query** Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&links_to_entry=4LgMotpNF6W20YKmuemW0a ``` ## Links to asset To search for entries which have a field linking to a specific asset, set the `links_to_asset` URI query parameter to the ID you want to search for. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&links_to_asset=wtrHxeu3zEoEce2MokCSi ``` ## Order You can order items in the response by specifying the `order` search parameter. You can use `sys` properties (such as `sys.createdAt`) or field values (such as `fields.myCustomDateField`) for ordering. **Note**: You must set the `content_type` URI query parameter to the ID of the content type you want to filter by. You can only use the following field types with the `order` parameter: | Name | JSON Primitive | Description | | ------- | -------------- | ------------------------------------------------------- | | Symbol | String | Basic list of characters. Maximum length is 256. | | Integer | Number | Number type without decimals. Values from -253 to 253. | | Number | Number | Number type with decimals. | | Date | String | Date/time in ISO-8601 format. | | Boolean | Boolean | Flag, `true` or `false`. | The following field types **do not** support the order parameter: | Name | JSON Primitive | Description | | ------ | -------------- | ----------------------------------------------------------------------------------- | | Text | String | Same as symbol, but can be filtered via full-text search. Maximum length is 50,000. | | Link | Object | See [links](/concepts/links) | | Array | Array | List of values. Value type depends on `field.items.type`. | | Object | Object | Arbitrary object. | If you don't pass an explicit order value the returned collection items will be ordered descending by publication timestamp (`sys.updatedAt`) and ascending by id (`sys.id`). This means that recently published items will appear closer to the top and for those with the same publication timestamp the order will be based on the items' ids. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&order=sys.createdAt ``` To retrieve all entries ordered by creation date. ## Reverse order You can reverse the sort order by prefixing the field with a `-` symbol. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&order=-sys.updatedAt ``` To order results by the time of the last update, newest to oldest. ## Order with multiple parameters You can order items by specifying the `order` parameter with attributes(`attribute`, `attribute2`). Prefix the field with a `-` sign to reverse the sort order of the attribute. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&order=sys.createdAt,sys.id ``` ## Limit You can specify the maximum number of results as a `limit` search parameter. **Note**: The maximum number of entries returned by the API is **1000**. The API will throw a `BadRequestError` for values higher than **1000** and values other than an integer. The default number of entries returned by the API is **100**. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&limit=3 ``` To limit results to 3 entries. ## Skip You can specify an offset with the `skip` search parameter. **Note**: The API will throw a `BadRequestError` for values less than **0** or values other than an integer. By combining `skip` and `limit` you can paginate through results: Page 1: skip=0, limit=15 Page 2: skip=15, limit=15 Page 3: skip=30, limit=15 etc. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&skip=3 ``` To skip 3 entries. > **Info** > > Don't use `skip` to iterate through an entire collection. Performance degrades as the offset grows, particularly for complex queries and deep link resolution. `skip`/`limit` is intended for random access into a bounded result set (for example, "page 3 of 20" in a UI). > > To fetch or process every item in a large collection, such as exports, analytics, migrations, or any exhaustive traversal, use [cursor pagination](/references/content-delivery-api/overview#cursor-pagination) instead. ## Filtering assets by MIME type You can filter assets by their MIME type group by using the `mimetype_group` query parameter. Valid groups are `attachment`, `plaintext`, `image`, `audio`, `video`, `richtext`, `presentation`, `spreadsheet`, `pdfdocument`, `archive`, `code` and `markup`. By default, the API will return all assets. Use the [Get all assets of a Space](/references/content-delivery-api/assets/get-all-assets) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/assets?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&mimetype_group=image ``` To return only image assets. ## Search on references You can search for entries based on the values of referenced entries. For example, if you want to find products of a particular brand, you can use search on references to find the products with one API request. ### Structure of a query Here's how the example above would look as a query: ``` content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.brand.sys.contentType.sys.id=sFzTZbSuM8coEwygeUYes&fields.brand.fields.companyName[match]=Lemnos ``` * First is the `content_type` parameter which you must include when you want to filter based on the values of the fields of entries of a certain content type. * Second is `fields.brand.sys.contentType.sys.id=`, which you use to filter on fields of entries from content type ``. * Third is `fields.brand.fields.companyName[match]=Lemnos` which filters entries to those branded as 'Lemnos'. > **Info** > > All filters on referenced entries are scoped with the path to the field that contains the reference. In the previous example that path is `fields.brand`. You can search on multiple references at once and combine them into one singe API query with a series of field and value pairs. ### Available nested filters You can use the `all`, `in`, `nin`, `exists`, `match`, `gt`, `gte`,`lt`, `lte`, `ne`, `near` and `within` filters when searching on references. The semantics of these filters are the same as when you use them on a non referenced entry. ### Restrictions Searching on references has the following restrictions: * You can only search on references on fields which link to a single entry. Fields which hold references to many entries or fields with references to assets are not supported. * The maximum number of reference searches in one query is **2**. A larger value will return an error. Use the [Get all entries of a Space](/references/content-delivery-api/entries/get-all-entries) endpoint, see example: ``` /spaces/yadj1kx9rmg0/environments/staging/entries?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.brand.sys.contentType.sys.id=sFzTZbSuM8coEwygeUYes&fields.brandcompanyNameLemnos ``` This example will return the Lemnos branded products.