---
title: "Query"
description: "Query"
url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/javascript/reference/query"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-22"
---

# Query

## Query

A Query holds one list request for a collection of the stack, such as the entries of a content type or the global fields of a stack. Use this object to

*   list the items of a collection that match a query condition
*   read only the first matching item
*   count the matching items

Call the query method of a collection object to get a Query, for example stack.contentType('<CONTENT\_TYPE\_UID>').entry().query(params) or stack.globalField().query(params). query sends nothing. The request goes out when you call [find](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-find), [findOne](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-findone) or [count](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-count).

## Class-Level Notes

**What a query contains.**

*   The request path of the collection that built it, for example /content\_types/{content\_type\_uid}/entries.
*   A copy of the params that you passed to query. The SDK sends params.query as query=<JSON> and every other key as a query parameter, with arrays in the key\[\]=value form.
*   A copy of the headers of the collection object, taken when you called query. A header that you add to the collection object later does not reach this query. Change the headers of the query itself with [addHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-addheader), [addHeaderDict](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-addheaderdict) and [removeHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-removeheader).

**One parameter map for all three calls.**

*   find, findOne and count send the same parameter map. findOne adds limit=1 to it and count adds count=true, and both values stay for every later call on the same query.
*   Call query again for each request when you mix these calls, so that each request starts from your own params.

**ContentstackCollection.** find and findOne resolve to a ContentstackCollection. Its properties come from the response body:

Property

Type

Access

Default

Description

items

object\[\]

Read

\[\]

The matching items, each one an object of the queried class, such as Entry.

count

number

Read

undefined

Total number of matching items, when the response has count.

schema

object

Read

undefined

Content type schema, when the response has schema.

content\_type

object

Read

undefined

Content type details, when the response has content\_type.

notice

string

Read

undefined

Message from the API, when the response has notice.

*   Each object in items has the methods of a single item of its class, for example fetch, update and delete on an Entry. It carries the headers of the query.
*   count resolves to the response body as the API returns it, not to a ContentstackCollection.

**Pagination.**

*   Each call sends one request and reads one page. The SDK does not request the next page.
*   Pass limit and skip in the params of query to read another page. Without them the API applies its own page size.

**Rate limiting and retry.**

*   This SDK automatically retries on 429 with configurable delay and attempt limits.

**Additional Resource:** For more information on the retry options and their defaults, refer to the [Contentstack](/docs/developers/sdks/content-management-sdk/javascript/reference/contentstack) documentation.

## Capability Matrix

Capability

Supported

Notes / Alternative

Read every page of a collection in one call

No

Call query again with a larger skip for each page

Chain filter methods such as where or limit

No

Pass the condition and options in the params of query

Reuse one query for count and then find

No

Call query again for each request

## Method Index

**Send the request.** Available on any Query.

Method Name

Returns

Description

[find](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-find)

The matching items.

Lists the matching items.

[findOne](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-findone)

The first matching item.

Reads the first matching item.

[count](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-count)

The API response with the number of matching items.

Counts the matching items.

**Set request headers.** Available on any Query.

Method Name

Returns

Description

[addHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-addheader)

The same query, for chaining.

Adds one request header.

[addHeaderDict](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-addheaderdict)

The same query, for chaining.

Adds several request headers.

[removeHeader](/docs/developers/sdks/content-management-sdk/javascript/reference/query#query-removeheader)

The same query, for chaining.

Removes one request header.

## Class-Level Snippet

The snippet below lists the entries of one content type whose title matches, ten at a time, and prints the total count.

```
import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({ query: { title: 'Hello' }, limit: 10, skip: 0, include_count: true })
    .find()
  console.log(result.count)
  for (const entry of result.items) {
    console.log(entry.uid, entry.title)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}
```

## Methods

Each method of the Query class has its own section below, with its parameters, validation rules, behavior, and examples.

## addHeader

addHeader adds one header to the request that this query sends.

```
Returns: Query. The same query, for chaining.
ValidationThere is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same query.An invalid value surfaces as a rejected promise from the find, findOne or count call that follows.BehaviorClient-side only. addHeader sends no request.The query holds its own copy of the headers, taken when you called query. The change applies to this query only, not to the collection object that built it.A key that the query already holds gets the new value.The items that find and findOne return carry the headers of the query.ExampleBasic usage: tag one list requestimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const query = stack.contentType('<CONTENT_TYPE_UID>').entry()
  .query({ query: { title: 'Hello' } })
  .addHeader('x-request-id', 'docs-123')
// find(), findOne() and count() on this query send the header
console.log(typeof query.find)
```

Header name, for example x-request-id.

Header value to send.

## addHeaderDict

addHeaderDict adds several headers to the request that this query sends.

```
Returns: Query. The same query, for chaining.
ValidationThere is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same query.An invalid value surfaces as a rejected promise from the find, findOne or count call that follows.BehaviorClient-side only. addHeaderDict sends no request.Copies every key of headerDict into the headers of this query. A key that the query already holds gets the new value.The change applies to this query only, not to the collection object that built it.ExampleBasic usage: send two extra headers with one list requestimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const query = stack.globalField()
  .query({ include_count: true })
  .addHeaderDict({ 'x-request-id': 'docs-123', 'x-team': 'docs' })
// find(), findOne() and count() on this query send both headers
console.log(typeof query.count)
```

Header names and values to add.

## count

count sends the query with count=true and reads the number of matching items.

This method takes no parameters.

```
Returns: Promise<Response>. The API response with the number of matching items.
Known issue: count keeps count=true on the query, so a later find or findOne on the same query sends it too and does not return the items you expect. Call query again before you call find.
ValidationThere is no client-side validation.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorSends the same GET request as find, with count=true added to the query parameters. Get all Releases describes count as returning only the total count, without the items.Resolves to the response body as the API returns it. The SDK does not wrap it in a ContentstackCollection and does not read the number out of it.To read the items and the total in one request, pass include_count: true to query and call find instead.ExampleBasic usage: count the entries with a given titleimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({ query: { title: 'Hello' } })
    .count()
  console.log(response)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}
```

## find

find sends the query and lists the items that match it.

This method takes no parameters.

```
Returns: Promise<ContentstackCollection>. The matching items.
ValidationThere is no client-side validation. find sends the params that you passed to query as they are.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorSends one GET request to the path of the collection that built the query, for example GET /v3/content_types/{content_type_uid}/entries, as Get all entries describes for entries.Resolves to a ContentstackCollection. items holds one object of the queried class per item in the response, with the methods of a single item.count holds the total when the response has it, for example when params include include_count: true.Reads one page. Pass limit and skip in the params of query to read another page.Sends limit=1 and count=true too when you called findOne or count on the same query before.ExampleBasic usage: list the entries of a content typeimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().query().find()
  for (const entry of result.items) {
    console.log(entry.uid, entry.title)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}Filter and paginate: read the second page of matching entriesimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({ query: { title: 'Hello' }, locale: '<LOCALE>', limit: 10, skip: 10, include_count: true })
    .find()
  console.log(`${result.items.length} of ${result.count}`)
  // Each item is an Entry with fetch, update and delete
  const first = result.items[0]
  if (first) {
    const entry = await first.fetch()
    console.log(entry.title)
  }
} catch (error) {
  console.error(error.errorMessage)
}
```

## findOne

findOne sends the query with limit=1 and reads the first item that matches.

This method takes no parameters.

```
Returns: Promise<ContentstackCollection>. The first matching item.
Known issue: findOne keeps limit=1 on the query, so a later find on the same query also returns one item. Call query again before you call find.
ValidationThere is no client-side validation.The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.No match is not an error. The promise resolves with an empty items array.Additional Resource: Refer to Content Management API Errors for the full error code list.
BehaviorSends the same GET request as find, with limit=1 added to the query parameters.Resolves to a ContentstackCollection, not to one item. Read the item at items[0].ExampleBasic usage: read the first entry with a given titleimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({ query: { title: 'Hello' } })
    .findOne()
  const entry = result.items[0]
  console.log(entry ? entry.uid : 'No entry matches')
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}
```

## removeHeader

removeHeader removes one header from the request that this query sends.

```
Returns: Query. The same query, for chaining.
ValidationThere is no client-side validation. A null or undefined key, or a key that the query does not hold, leaves the headers unchanged.An invalid value surfaces as a rejected promise from the find, findOne or count call that follows.BehaviorClient-side only. removeHeader sends no request.Removes the key from the headers of this query only. The collection object that built the query keeps it.The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.ExampleBasic usage: send a list request without the branch headerimport contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

const query = stack.contentType().query().removeHeader('branch')
// This query reads the content types of the default branch
console.log(typeof query.find)
```

Name of the header to remove.

## Query | JavaScript Management SDK | Contentstack

The Query object in the JavaScript Management SDK sends a list request for a collection, such as entries or content types, and returns the matching items.