# List all records

To retrieve a collection of records, send a GET request to the `/items` endpoint. The collection is [paginated](https://www.datocms.com/docs/content-management-api/pagination.md), so make sure to iterate over all the pages if you need every record in the collection!

> [!PROTIP] 📚 New to DatoCMS records?
> Begin by reading the [Introduction to records](https://www.datocms.com/docs/content-management-api/resources/item.md) guide to familiarize yourself with field types, API response modes, and the concepts of block manipulation!

## Filter combinations

You can use multiple filters to refine the records you want to retrieve. However, some combinations may be invalid, resulting in errors or ignored filters, which can lead to unexpected results:

-   `filter[ids]` cannot be combined with `filter[type]`, or `filter[fields]` related to model-specific fields
-   `filter[type]`, when specifying multiple item types, cannot be combined with `filter[ids]`, or `filter[fields]` related to model-specific fields
-   `filter[type]`, when specifying one (or more) block models, cannot be combined with `filter[ids]`, `filter[fields]`, or `query`

## Response modes: Regular vs. Nested

The `GET /items` endpoint, just like the [single record endpoint](https://www.datocms.com/docs/content-management-api/resources/item/self.md), supports two different response modes that control how block fields are returned in the JSON payload. You can switch between them using the nested query parameter.

-   **Regular mode (default)**: This is the most efficient mode for listing multiple records. Any block fields (like Modular Content) will contain an array of **block IDs**, not the full block content. This keeps the response size small and fast.
-   **Nested mode (`nested=true`)**: This mode returns the complete content for any block fields. Instead of just IDs, the API will return full **block objects**, including all their attributes. This is useful when you need to display the blocks' content immediately without making additional API calls, or to read existing content and then make an update.

###### Example Regular mode (default)

Please note that if you don't specify any parameters, the API will return return the first 30 records. They can be from **any** model in your project.

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Article
 * ├─ title: string
 * └─ content: text
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const results = await client.items.list<Schema.Article>({
    version: "current",
  });

  console.log("-- LISTING ITEMS --");
  results.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

Showing the default number of results (30 records) from any model

```javascript
-- LISTING ITEMS --
└ Item "cEzRZmM3SyeHmAxS5KE9dg" (item_type: "T6TO3fbwRdyhcljYV8fyhg")
  ├ title: "Third Article"
  └ content: "This is the content of the third article."

└ Item "f2Ev8ybUTq6DFk348JeW1w" (item_type: "T6TO3fbwRdyhcljYV8fyhg")
  ├ title: "Second Article"
  └ content: "This is the content of the second article."

└ Item "VJ2-B9zJQPG-xdwU-vJdOw" (item_type: "T6TO3fbwRdyhcljYV8fyhg")
  ├ title: "First Article"
  └ content: "This is the content of the first article."
```


###### Example Nested mode

> [!WARNING] Lower limits apply with Nested Mode
> When `nested: true`, the maximum number of records you can request at once is restricted to 30, in contrast to the standard 500.

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * BlogPost
 * ├─ title: string
 * └─ content: structured_text
 *    ├─ HeroBlock: headline, subtitle
 *    ├─ TextBlock: content
 *    └─ ImageBlock: image, caption
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const records = await client.items.list<Schema.BlogPost>({
    nested: true, // But retrieve its nested block content as well
    version: "current",
  });

  console.log("-- RECORDS WITH NESTED BLOCKS --");
  records.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

```javascript
-- RECORDS WITH NESTED BLOCKS --
└ Item "ZJ3ESh8pTBaRS5ED8loc2w" (item_type: "U4jwHd5-RCy2ItsDuWLMTQ")
  ├ title: "Understanding Modular Content"
  └ content
    ├ heading (level: 1)
    │ └ span "Welcome to Modular Content"
    ├ block
    │ └ Item "Sb5aNY5hQHaN_4KMU96H6A" (item_type: "GURToKAcQIyC-rTypPeHTw")
    │   ├ headline: "Hero Section"
    │   └ subtitle: "This is a hero block that introduces the content"
    ├ paragraph
    │ └ span "This blog post demonstrates how to work with structured text and modu..."
    ├ block
    │ └ Item "G_06E4v8SvqdChpFnEELxA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
    │   └ content: "Modular content allows you to create flexible, reusable components that can b..."
    ├ block
    │ └ Item "T2lBvPruQwGAQTM9_ywm-g" (item_type: "ZsoQdbEVTkizaFPrama3IA")
    │   ├ image
    │   │ └ upload_id: "dLJdPzC3TW-mJXGo7K73Gg"
    │   └ caption: "A beautiful landscape showcasing the power of visual content"
    └ paragraph
      └ span "This concludes our example of nested blocks and structured content."

└ Item "T2lBvPruQwGAQTM9_ywm-g" (item_type: "ZsoQdbEVTkizaFPrama3IA")
  ├ image
  │ └ upload_id: "dLJdPzC3TW-mJXGo7K73Gg"
  └ caption: "A beautiful landscape showcasing the power of visual content"

└ Item "G_06E4v8SvqdChpFnEELxA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  └ content: "Modular content allows you to create flexible, reusable components that can b..."

└ Item "Sb5aNY5hQHaN_4KMU96H6A" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ headline: "Hero Section"
  └ subtitle: "This is a hero block that introduces the content"
```

## TypeScript typing

Iterating records without typed schemas means every attribute on every returned record is `unknown`, and filters on model-specific fields go unchecked. The single biggest lever you have is passing a generated `Schema.X` marker as the generic on `items.list` (or `items.listPagedIterator`). TypeScript then knows the exact shape of each returned record — its field names, types, and block structures — so reads are typed end-to-end:

```ts
import * as Schema from "./schema";

for await (const record of client.items.listPagedIterator<Schema.Article>({
  filter: { type: "article_model_id" },
})) {
  record.title; // typed, not unknown
}
```

For the exact type of a specific field on the returned records (to annotate a helper or intermediate variable), index `ApiTypes.Item<Schema.Article>["field_api_key"]` (or `ApiTypes.ItemInNestedResponse<Schema.Article>["field_api_key"]` when iterating with `nested: true`). See the [full TypeScript guide](https://www.datocms.com/cma-ts-schema.md) for how to generate `schema.ts` and the complete pattern.

The following table contains the list of all the possible arguments, along with their type, description and examples values.

## Query parameters

**`nested`**

- Type: boolean

For Modular Content, Structured Text and Single Block fields. If set, returns full payload for nested blocks instead of IDs

**`filter`**

- Type: object

Attributes to filter records

<details>
<summary>Show object format</summary>

**`ids`**

- Type: string
- Example: `"c89tCUarTvGKxA37acCEWA,aCiWeOsUT3mxY0KIzUfAhw"`

Record (or block record) IDs to fetch, comma separated. If you use this filter, you _must not_ use `filter[type]`. You can combine it with meta fields (like `_published_at`, `_status`), but _must not_ use model-specific fields

**`type`**

- Type: string
- Example: `"cat,dog"`

Model/Block model ID or `api_key` to filter. If you use this filter, you _must not_ use `filter[ids]`. When passing a single element, you can use both meta fields and model-specific fields (note: model-specific fields only work with models, not block models). When passing multiple comma-separated values, you can use meta fields but _must not_ use model-specific fields

**`query`**

- Type: string
- Example: `"foo"`

Textual query to match. Can be combined with other filters. When used, only records (not blocks) are returned. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used.

**`fields`**

- Type: object
- Example: `{ name: { eq: "Buddy" } }`

Filter by record fields. Meta fields (like `_published_at`, `_status`) can be used in most cases. Model-specific fields (like `title`, `name`) require `filter[type]` to specify a single model, and only work with models (not block models). Same syntax as [GraphQL API records filters](/docs/content-delivery-api/filtering-records): use square brackets to indicate nesting levels. E.g. `filter[fields][parent][eq]=<ID_VALUE>`. Use snake_case for field names. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used.

**`only_valid`**

- Type: string
- Example: `"true"`

When set, only valid records are included in the results.

</details>

**`locale`**

- Type: string
- Example: `"it"`

When `filter[query]` or `field[fields]` is defined, filter by this locale. Default: environment's main locale

**`page`**

- Type: object

Parameters to control offset-based pagination

<details>
<summary>Show object format</summary>

**`offset`**

- Type: integer
- Example: `200`

The (zero-based) offset of the first entity returned in the collection (defaults to 0)

**`limit`**

- Type: integer

The maximum number of entities to return (defaults to 30, maximum is 500)

</details>

**`order_by`**

- Type: string
- Example: `"name_DESC"`

Fields used to order results. You **must** specify also `filter[type]` with one element only to be able use this option. Format: `<field_name>_(ASC|DESC)`, where `<field_name>` can be either the API key of a model's field, or one of the following meta columns: `id`, `_updated_at`, `_created_at`, `_status`, `_published_at`, `_first_published_at`, `_publication_scheduled_at`, `_unpublishing_scheduled_at`, `_is_valid`, `position` (only for sortable models). You can pass multiple comma separated rules.

**`version`**

- Type: string
- Example: `"published"`

Whether you want the currently published versions (`published`) of your records, or the latest available (`current`, default)

## Returns

Returns an array of resource objects of type [item](https://www.datocms.com/docs/content-management-api/resources/item.md)

## Other examples

###### Example Fetching a specific page of records

To fetch a specific page, you can use the `page` object in the query params together with its `offset` and `limit` parameters. They will still be from **any model** in your project.

Code

To get 2 records starting from position 4, we should use: `limit: 2` and `offset: 3` (because record counting starts from 0)

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * BlogPost
 * ├─ title: string
 * ├─ content: text
 * └─ author: string
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const twoRecords = await client.items.list<Schema.BlogPost>({
    page: {
      limit: 2,
      offset: 3,
    },
    version: "current",
  });

  console.log("-- PAGINATED ITEMS --");
  twoRecords.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

```javascript
-- PAGINATED ITEMS --
└ Item "G9k168YbTietmuwlA7-evg" (item_type: "P--WAiOJQraTyQb3pwnNog")
  ├ title: "GraphQL Queries in DatoCMS"
  ├ content: "How to write efficient GraphQL queries to fetch your content."
  └ author: "Bob GraphQL"

└ Item "Wgx-4iIaTTWsjgj7kjxV1w" (item_type: "P--WAiOJQraTyQb3pwnNog")
  ├ title: "Using the Management API"
  ├ content: "A comprehensive guide to using the DatoCMS Content Management API."
  └ author: "Alice Engineer"
```


###### Example Fetching all pages

Instead of fetching a single page at a time, sometimes you want to get all the pages together.

You can do this using the `client.items.listPagedIterator()` method with an [async iteration statement](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of), which will handle pagination for you. All the details on how to use `listPagedIterator()` are outlined [on this page](https://www.datocms.com/docs/content-management-api/pagination.md#paged-iterators).

Note that this will return records across **all** your models, unless you specify a filter. Unfiltered, this is useful for fetching all the records in your project (e.g. for backup or export purposes). To filter by IDs or models, see the other examples below.

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Product
 * ├─ name: string
 * └─ price: float
 *
 * Category
 * ├─ name: string
 * └─ description: text
 *
 * Review
 * ├─ rating: integer
 * └─ comment: text
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  // We'll be building up an array of all records using an AsyncIterator, `client.items.listPagedIterator()`
  const allRecords = [];

  for await (const record of client.items.listPagedIterator<
    Schema.Product | Schema.Category | Schema.Review
  >({ version: "current" })) {
    allRecords.push(record);
  }

  console.log("-- ALL RECORDS ACROSS ALL PAGES --");
  allRecords.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

Showing all results of `client.items.listPagedIterator()`, from any model

```javascript
-- ALL RECORDS ACROSS ALL PAGES --
└ Item "ApidnkdFSgSa0fMnxut7ug" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Audio"
  └ description: "Audio equipment and sound devices"

└ Item "PeKN3Mx1QMiQpxR6rIfV1Q" (item_type: "ZsoQdbEVTkizaFPrama3IA")
  ├ rating: 5
  └ comment: "Excellent product, highly recommended!"

└ Item "Fo_aNiUGQce74zJQLghgEA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Electronics"
  └ description: "Electronic devices and accessories"

└ Item "DfAtrqEiQC-BpxRkCgFxug" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Bluetooth Speaker"
  └ price: 49.99

└ Item "XfVkvL9YT2K0KrhaqEXtrg" (item_type: "ZsoQdbEVTkizaFPrama3IA")
  ├ rating: 4
  └ comment: "Good quality, worth the price."

└ Item "d2InAHvfQze_HvxdtX3Iyw" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Wireless Headphones"
  └ price: 99.99
```


###### Example Fetching records by their IDs

You can retrieve a list of records (or blocks) by their record IDs. They can be from the same or different models.

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Dog
 * ├─ name: string
 * └─ breed: string
 *
 * Song
 * ├─ title: string
 * ├─ artist: string
 * └─ duration: integer
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const records = await client.items.list<Schema.Dog | Schema.Song>({
    filter: {
      // Specific record IDs: one dog record, and one song record
      // Note that it's a comma-separated string with no spaces
      ids: "ZsoQdbEVTkizaFPrama3IA,U4jwHd5-RCy2ItsDuWLMTQ",
    },
    version: "current",
  });

  console.log("-- ITEMS BY SPECIFIC IDS --");
  records.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

Showing two records from different models: dog and song. The returned record order is random, not the order of the record IDs you specified.

```javascript
-- ITEMS BY SPECIFIC IDS --
└ Item "U4jwHd5-RCy2ItsDuWLMTQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ title: "Bohemian Rhapsody"
  ├ artist: "Queen"
  └ duration: 355

└ Item "ZsoQdbEVTkizaFPrama3IA" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Buddy"
  └ breed: "Golden Retriever"
```


###### Example Fetching records belonging to a model

You can filter the records by one or more model types. You can use either the model's `api_key` (that you define) or its unique ID (generated by DatoCMS). Multiple comma-separated values are accepted:

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Cat
 * ├─ name: string
 * ├─ breed: string
 * └─ age: integer
 *
 * Dog
 * ├─ name: string
 * ├─ breed: string
 * └─ age: integer
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const records = await client.items.list<Schema.Cat | Schema.Dog>({
    filter: {
      // Filtering by the model with api_key "cat" and the model with ID of "dog"
      type: "cat,Y5l8wbEDQLKj7qm22CTucQ",
    },
    version: "current",
  });

  console.log("-- FILTERED BY MODEL TYPE --");
  records.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

```javascript
-- FILTERED BY MODEL TYPE --
└ Item "bVlcRGmFRqiK1nKPbesN8w" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Mittens"
  ├ breed: "Siamese"
  └ age: 2

└ Item "CEtirbQ_SnmHpowQ2tZ-ow" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Max"
  ├ breed: "Labrador"
  └ age: 4

└ Item "KyueUsNkQfWh71dfxstVWQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Buddy"
  ├ breed: "Golden Retriever"
  └ age: 5

└ Item "bRfo6K_YRJa1RrPfpUQTOg" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Whiskers"
  ├ breed: "Persian"
  └ age: 3
```


###### Example Fetching draft or updated records and filtering by publication status

By default, the API only returns published records. Using the `version` parameter, you can choose to also include drafts and updates.

`version: 'current'` will return the *most recent* versions of the queried records. Sometimes this can be the same as the published version, but other times it could be an unpublished draft or update:

-   `draft` means the record has been created and saved, but not yet published (or was unpublished)
-   `published` means the record has been published, and there are no later changes (i.e., the published version *is* the most recent version)
-   `updated` means the record was previously published, but there are new changes that have been saved and not yet published (the current version is *ahead* of the published version)

To get *only* draft, updated, or published records, you can filter on this response's `record.meta.status` property on the client side, *after* the fetch:

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Post
 * ├─ title: string
 * ├─ content: text
 * └─ author: string
 */

const getPublishedAndDraftRecordsOfModel = async () => {
  const client = buildClient({
    apiToken: process.env.DATOCMS_API_TOKEN,
  });

  const allRecords = await client.items.list<Schema.Post>({
    filter: {
      type: "post", // Model name or internal ID
    },
    version: "current", // Fetch the latest version of the records, regardless of publication status
  });

  // Records that have been saved but not published (or were unpublished later)
  const newDraftsOnly = allRecords.filter(
    (record) => record.meta.status === "draft",
  );

  // Records that were published but have unsaved changes ahead of the published version
  const updatedRecordsOnly = allRecords.filter(
    (record) => record.meta.status === "updated",
  );

  // Records that were published and have no further changes
  const publishedRecordsOnly = allRecords.filter(
    (record) => record.meta.status === "published",
  );

  console.log(`There are ${allRecords.length} total records in this model.`);
  console.log(`${publishedRecordsOnly.length} are published.`);
  console.log(`${updatedRecordsOnly.length} have unpublished updates.`);
  console.log(`${newDraftsOnly.length} are unpublished drafts.`);

  console.log("\n-- PUBLISHED RECORDS --");
  publishedRecordsOnly.forEach((item) => {
    console.log(inspectItem(item));
  });

  console.log("\n-- DRAFT RECORDS --");
  newDraftsOnly.forEach((item) => {
    console.log(inspectItem(item));
  });

  console.log("\n-- UPDATED RECORDS --");
  updatedRecordsOnly.forEach((item) => {
    console.log(inspectItem(item));
  });
};

getPublishedAndDraftRecordsOfModel();
```

Returned output

```javascript
There are 4 total records in this model.
2 are published.
1 have unpublished updates.
1 are unpublished drafts.

-- PUBLISHED RECORDS --
└ Item "Z1iG3QGISZON0p6ctQR7bg" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ title: "Another Published Post"
  ├ content: "This is another published post to show multiple published items."
  └ author: "Alice Publisher"

└ Item "Ssc2tQvNS-i0yjrcmq824A" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ title: "Published Article"
  ├ content: "This is a published article that's live on the website."
  └ author: "John Author"

-- DRAFT RECORDS --
└ Item "cjwt438ZT2ChDWpolIm2Sg" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ title: "Draft Article"
  ├ content: "This is a draft article that hasn't been published yet."
  └ author: "Jane Writer"

-- UPDATED RECORDS --
└ Item "YWrNII0ETpWdjXaO76AW3Q" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ title: "Updated Article [EDITED]"
  ├ content: "This article was published but then updated with new content."
  └ author: "Bob Editor"
```


###### Example Filtering a model's records by field values and sorting the results

Within a specified model, you can further filter its records by their field values.

You **must** specify a single model using `filter[type]`. You *cannot* filter by field value across multiple models at once.

Valid filters are documented at [GraphQL API records filters](https://www.datocms.com/docs/content-delivery-api/filtering-records.md), so please check there. However, you **cannot** use [deep filtering](https://www.datocms.com/docs/content-delivery-api/deep-filtering.md) on Modular Content and Structured Text fields at the moment.

-   You *may* add an optional `locale` parameter if you are filtering by a localized field.
-   You *may* add an optional `order_by` parameter.

In this example, we are filtering the model `dog` by:

-   A single-line string field, `name in ['Buddy','Rex']` (matching `Buddy` OR `Rex`)
-   A single-line string field, `breed eq 'mixed'` (matching exactly `mixed`)
-   A date field (`_updated_at`) (and ordering the results by the same)

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Dog
 * ├─ name: string
 * ├─ breed: string
 * ├─ age: integer
 * ├─ weight: float
 * └─ is_trained: boolean
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const records = await client.items.list<Schema.Dog>({
    filter: {
      type: "dog",
      fields: {
        name: {
          in: ["Buddy", "Rex"],
        },
        breed: {
          eq: "mixed",
        },
        _updated_at: {
          gt: "2020-04-18T00:00:00",
        },
      },
    },
    order_by: "_updated_at_ASC",
    version: "current",
  });

  console.log("-- FILTERED BY FIELD VALUES --");
  records.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

```javascript
-- FILTERED BY FIELD VALUES --
└ Item "bxiqfMHRTxaB1sv4bedQTQ" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Buddy"
  ├ breed: "mixed"
  ├ age: 5
  ├ weight: 25.5
  └ is_trained: true

└ Item "d9f4ZoN_T9WqJRtC-jVu_A" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Rex"
  ├ breed: "mixed"
  ├ age: 3
  ├ weight: 30.2
  └ is_trained: false
```


###### Example Fetching records by a textual generic query

You can retrieve a list of records filtered by a textual query match. It will search in block records content too. Set the `nested` parameter to `true` to retrieve embedded block content as well.

> [!WARNING] Content indexing delay
> Please note that you need to wait at least 30 seconds after creating or updating content before expecting to see results in textual queries.

You *can* narrow your search to some models by specifying the `filter[type]` parameter. You can use either the model's `api_key` or its unique ID. Multiple comma-separated values are accepted.

You *should* specify the `locale` attribute, or the environment's default locale will be used.

Returned records are ordered by rank.

Code

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import type * as Schema from "./schema.js";

/*
 * Dog
 * ├─ name: string
 * ├─ description: text
 * └─ breed: string
 *
 * Cat
 * ├─ name: string
 * ├─ description: text
 * └─ breed: string
 */

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const records = await client.items.list<Schema.Dog | Schema.Cat>({
    filter: {
      // optional, if defined, search in the specified models only
      type: "dog,cat",
      query: "chicken",
    },
    locale: "en",
    order_by: "_rank_DESC", // possible values: `_rank_DESC` (default) | `_rank_ASC`
    version: "current",
  });

  console.log("-- SEARCH RESULTS FOR 'chicken' --");
  records.forEach((item) => {
    console.log(inspectItem(item));
  });
}

run();
```

Returned output

```javascript
-- SEARCH RESULTS FOR 'chicken' --
└ Item "c2c5cXrITwOhj972XxEIsQ" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Luna"
  ├ description: "A playful Labrador puppy who enjoys swimming and chicken-flavored treats."
  └ breed: "Labrador"

└ Item "LlduEUcCSd-M2F5fZARUAw" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Mittens"
  ├ description: "A curious Siamese cat who loves chicken and exploring high places."
  └ breed: "Siamese"

└ Item "L45_GuAKQCGfcNtLE4gjKA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
  ├ name: "Shadow"
  ├ description: "A mysterious black cat who prefers fish over chicken and sleeps during the day."
  └ breed: "Domestic Shorthair"

└ Item "E0Y-kR8iSC-EooTe7dHx6w" (item_type: "GURToKAcQIyC-rTypPeHTw")
  ├ name: "Buddy"
  ├ description: "A friendly golden retriever who loves to play fetch and enjoys chicken treats..."
  └ breed: "Golden Retriever"
```

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)
- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)
- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)
- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)
- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [CMA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-management-api/technical-limits.md)
- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances.md)
- [Create a new record](https://www.datocms.com/docs/content-management-api/resources/item/create.md)
- [Duplicate a record](https://www.datocms.com/docs/content-management-api/resources/item/duplicate.md)
- [Update a record](https://www.datocms.com/docs/content-management-api/resources/item/update.md)
- [Referenced records](https://www.datocms.com/docs/content-management-api/resources/item/references.md)
- [Retrieve a record](https://www.datocms.com/docs/content-management-api/resources/item/self.md)
- [Delete a record](https://www.datocms.com/docs/content-management-api/resources/item/destroy.md)
- [Publish a record](https://www.datocms.com/docs/content-management-api/resources/item/publish.md)
- [Unpublish a record](https://www.datocms.com/docs/content-management-api/resources/item/unpublish.md)
- [Publish items in bulk](https://www.datocms.com/docs/content-management-api/resources/item/bulk_publish.md)
- [Unpublish items in bulk](https://www.datocms.com/docs/content-management-api/resources/item/bulk_unpublish.md)
- [Destroy items in bulk](https://www.datocms.com/docs/content-management-api/resources/item/bulk_destroy.md)
- [Move items to stage in bulk](https://www.datocms.com/docs/content-management-api/resources/item/bulk_move_to_stage.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)
- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)
- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)
- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)