Content Management API > Record

List all records

To retrieve a collection of records, send a GET request to the /items endpoint. The collection is paginated, so make sure to iterate over all the pages if you need every record in the collection!

📚 New to DatoCMS records?

Begin by reading the Introduction to records guide to familiarize yourself with field types, API response modes, and the concepts of block manipulation!

Response modes: Regular vs. Nested

The GET /items endpoint, just like the single record endpoint, 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.

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.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Article
11
 * ├─ title: string
12
 * └─ content: text
13
 */
14

15
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
16

17
type Article = ItemTypeDefinition<
18
  EnvironmentSettings,
19
  "T6TO3fbwRdyhcljYV8fyhg",
20
  {
21
    title: { type: "string" };
22
    content: { type: "text" };
23
  }
24
>;
25

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

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

32
  console.log("-- LISTING ITEMS --");
33
  results.forEach((item) => {
34
    console.log(inspectItem(item));
35
  });
36
}
37

38
run();

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

1
-- LISTING ITEMS --
2
└ Item "cEzRZmM3SyeHmAxS5KE9dg" (item_type: "T6TO3fbwRdyhcljYV8fyhg")
3
  ├ title: "Third Article"
4
  └ content: "This is the content of the third article."
5

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

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

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.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * BlogPost
11
 * ├─ title: string
12
 * └─ content: structured_text
13
 *    ├─ HeroBlock: headline, subtitle
14
 *    ├─ TextBlock: content
15
 *    └─ ImageBlock: image, caption
16
 */
17

18
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
19

20
type HeroBlock = ItemTypeDefinition<
21
  EnvironmentSettings,
22
  "GURToKAcQIyC-rTypPeHTw",
23
  {
24
    headline: { type: "string" };
25
    subtitle: { type: "text" };
26
  }
27
>;
28

29
type TextBlock = ItemTypeDefinition<
30
  EnvironmentSettings,
31
  "Y5l8wbEDQLKj7qm22CTucQ",
32
  {
33
    content: { type: "text" };
34
  }
35
>;
36

37
type ImageBlock = ItemTypeDefinition<
38
  EnvironmentSettings,
39
  "ZsoQdbEVTkizaFPrama3IA",
40
  {
41
    image: { type: "file" };
42
    caption: { type: "string" };
43
  }
44
>;
45

46
type BlogPost = ItemTypeDefinition<
47
  EnvironmentSettings,
48
  "U4jwHd5-RCy2ItsDuWLMTQ",
49
  {
50
    title: { type: "string" };
51
    content: {
52
      type: "structured_text";
53
      blocks: HeroBlock | TextBlock | ImageBlock;
54
    };
55
  }
56
>;
57

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

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

67
  console.log("-- RECORDS WITH NESTED BLOCKS --");
68
  records.forEach((item) => {
69
    console.log(inspectItem(item));
70
  });
71
}
72

73
run();

1
-- RECORDS WITH NESTED BLOCKS --
2
└ Item "ZJ3ESh8pTBaRS5ED8loc2w" (item_type: "U4jwHd5-RCy2ItsDuWLMTQ")
3
  ├ title: "Understanding Modular Content"
4
  └ content
5
    ├ heading (level: 1)
6
    │ └ span "Welcome to Modular Content"
7
    ├ block
8
    │ └ Item "Sb5aNY5hQHaN_4KMU96H6A" (item_type: "GURToKAcQIyC-rTypPeHTw")
9
    │   ├ headline: "Hero Section"
10
    │   └ subtitle: "This is a hero block that introduces the content"
11
    ├ paragraph
12
    │ └ span "This blog post demonstrates how to work with structured text and modu..."
13
    ├ block
14
    │ └ Item "G_06E4v8SvqdChpFnEELxA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
15
    │   └ content: "Modular content allows you to create flexible, reusable components that can b..."
16
    ├ block
17
    │ └ Item "T2lBvPruQwGAQTM9_ywm-g" (item_type: "ZsoQdbEVTkizaFPrama3IA")
18
    │   ├ image
19
    │   │ └ upload_id: "dLJdPzC3TW-mJXGo7K73Gg"
20
    │   └ caption: "A beautiful landscape showcasing the power of visual content"
21
    └ paragraph
22
      └ span "This concludes our example of nested blocks and structured content."
23

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

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

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

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

Query parameters

nested boolean

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

filter object

Attributes to filter records

ids string

Record (or block record) IDs to fetch, comma separated. If you use this filter, you must not use filter[type] or filter[fields]

Example:

"c89tCUarTvGKxA37acCEWA,aCiWeOsUT3mxY0KIzUfAhw"

type string

Model ID or api_key to filter. If you use this filter, you must not use filter[ids]. Comma separated values are accepted, but you must not use filter[fields] in this case

Example:

"cat,dog"

query string

Textual query to match. You must not use filter[ids]. If locale is defined, search within that locale. Otherwise environment's main locale will be used.

Example:

"foo"

fields object

Same as GraphQL API records filters: you must use square brackets to indicate nesting levels. E.g. if you wanna filter by parent record in a tree of records, you must use filter[fields][parent][eq]=<ID_VALUE>. Use snake_case for fields names. If locale is defined, search within that locale. Otherwise environment's main locale will be used.

Example:

{ name: { eq: "Buddy" } }

only_valid string

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

Example:

"true"

locale string

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

Example:

"it"

page object

Parameters to control offset-based pagination

offset integer

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

Example:

limit integer

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

order_by string

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.

Example:

"name_DESC"

version string

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

Example:

"current"

Returns

Returns an array of resource objects of type item

Other examples

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.

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

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * BlogPost
11
 * ├─ title: string
12
 * ├─ content: text
13
 * └─ author: string
14
 */
15

16
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
17

18
type BlogPost = ItemTypeDefinition<
19
  EnvironmentSettings,
20
  "P--WAiOJQraTyQb3pwnNog",
21
  {
22
    title: { type: "string" };
23
    content: { type: "text" };
24
    author: { type: "string" };
25
  }
26
>;
27

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

32
  const twoRecords = await client.items.list<BlogPost>({
33
    page: {
34
      limit: 2,
35
      offset: 3,
36
    },
37
    version: "current",
38
  });
39

40
  console.log("-- PAGINATED ITEMS --");
41
  twoRecords.forEach((item) => {
42
    console.log(inspectItem(item));
43
  });
44
}
45

46
run();

1
-- PAGINATED ITEMS --
2
└ Item "G9k168YbTietmuwlA7-evg" (item_type: "P--WAiOJQraTyQb3pwnNog")
3
  ├ title: "GraphQL Queries in DatoCMS"
4
  ├ content: "How to write efficient GraphQL queries to fetch your content."
5
  └ author: "Bob GraphQL"
6

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

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, which will handle pagination for you. All the details on how to use listPagedIterator() are outlined on this page.

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.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Product
11
 * ├─ name: string
12
 * └─ price: float
13
 *
14
 * Category
15
 * ├─ name: string
16
 * └─ description: text
17
 *
18
 * Review
19
 * ├─ rating: integer
20
 * └─ comment: text
21
 */
22

23
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
24

25
type Product = ItemTypeDefinition<
26
  EnvironmentSettings,
27
  "GURToKAcQIyC-rTypPeHTw",
28
  {
29
    name: { type: "string" };
30
    price: { type: "float" };
31
  }
32
>;
33

34
type Category = ItemTypeDefinition<
35
  EnvironmentSettings,
36
  "Y5l8wbEDQLKj7qm22CTucQ",
37
  {
38
    name: { type: "string" };
39
    description: { type: "text" };
40
  }
41
>;
42

43
type Review = ItemTypeDefinition<
44
  EnvironmentSettings,
45
  "ZsoQdbEVTkizaFPrama3IA",
46
  {
47
    rating: { type: "integer" };
48
    comment: { type: "text" };
49
  }
50
>;
51

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

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

59
  for await (const record of client.items.listPagedIterator<
60
    Product | Category | Review
61
  >({ version: "current" })) {
62
    allRecords.push(record);
63
  }
64

65
  console.log("-- ALL RECORDS ACROSS ALL PAGES --");
66
  allRecords.forEach((item) => {
67
    console.log(inspectItem(item));
68
  });
69
}
70

71
run();

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

1
-- ALL RECORDS ACROSS ALL PAGES --
2
└ Item "ApidnkdFSgSa0fMnxut7ug" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
3
  ├ name: "Audio"
4
  └ description: "Audio equipment and sound devices"
5

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

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

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

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

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

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

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Dog
11
 * ├─ name: string
12
 * └─ breed: string
13
 *
14
 * Song
15
 * ├─ title: string
16
 * ├─ artist: string
17
 * └─ duration: integer
18
 */
19

20
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
21

22
type Dog = ItemTypeDefinition<
23
  EnvironmentSettings,
24
  "GURToKAcQIyC-rTypPeHTw",
25
  {
26
    name: { type: "string" };
27
    breed: { type: "string" };
28
  }
29
>;
30

31
type Song = ItemTypeDefinition<
32
  EnvironmentSettings,
33
  "Y5l8wbEDQLKj7qm22CTucQ",
34
  {
35
    title: { type: "string" };
36
    artist: { type: "string" };
37
    duration: { type: "integer" };
38
  }
39
>;
40

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

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

54
  console.log("-- ITEMS BY SPECIFIC IDS --");
55
  records.forEach((item) => {
56
    console.log(inspectItem(item));
57
  });
58
}
59

60
run();

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

1
-- ITEMS BY SPECIFIC IDS --
2
└ Item "U4jwHd5-RCy2ItsDuWLMTQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
3
  ├ title: "Bohemian Rhapsody"
4
  ├ artist: "Queen"
5
  └ duration: 355
6

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

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:

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Cat
11
 * ├─ name: string
12
 * ├─ breed: string
13
 * └─ age: integer
14
 *
15
 * Dog
16
 * ├─ name: string
17
 * ├─ breed: string
18
 * └─ age: integer
19
 */
20

21
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
22

23
type Cat = ItemTypeDefinition<
24
  EnvironmentSettings,
25
  "GURToKAcQIyC-rTypPeHTw",
26
  {
27
    name: { type: "string" };
28
    breed: { type: "string" };
29
    age: { type: "integer" };
30
  }
31
>;
32

33
type Dog = ItemTypeDefinition<
34
  EnvironmentSettings,
35
  "Y5l8wbEDQLKj7qm22CTucQ",
36
  {
37
    name: { type: "string" };
38
    breed: { type: "string" };
39
    age: { type: "integer" };
40
  }
41
>;
42

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

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

55
  console.log("-- FILTERED BY MODEL TYPE --");
56
  records.forEach((item) => {
57
    console.log(inspectItem(item));
58
  });
59
}
60

61
run();

1
-- FILTERED BY MODEL TYPE --
2
└ Item "bVlcRGmFRqiK1nKPbesN8w" (item_type: "GURToKAcQIyC-rTypPeHTw")
3
  ├ name: "Mittens"
4
  ├ breed: "Siamese"
5
  └ age: 2
6

7
└ Item "CEtirbQ_SnmHpowQ2tZ-ow" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
8
  ├ name: "Max"
9
  ├ breed: "Labrador"
10
  └ age: 4
11

12
└ Item "KyueUsNkQfWh71dfxstVWQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ")
13
  ├ name: "Buddy"
14
  ├ breed: "Golden Retriever"
15
  └ age: 5
16

17
└ Item "bRfo6K_YRJa1RrPfpUQTOg" (item_type: "GURToKAcQIyC-rTypPeHTw")
18
  ├ name: "Whiskers"
19
  ├ breed: "Persian"
20
  └ age: 3

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:

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Post
11
 * ├─ title: string
12
 * ├─ content: text
13
 * └─ author: string
14
 */
15

16
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
17

18
type Post = ItemTypeDefinition<
19
  EnvironmentSettings,
20
  "GURToKAcQIyC-rTypPeHTw",
21
  {
22
    title: { type: "string" };
23
    content: { type: "text" };
24
    author: { type: "string" };
25
  }
26
>;
27

28
const getPublishedAndDraftRecordsOfModel = async () => {
29
  const client = buildClient({
30
    apiToken: process.env.DATOCMS_API_TOKEN,
31
  });
32

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

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

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

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

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

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

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

70
  console.log("\n-- UPDATED RECORDS --");
71
  updatedRecordsOnly.forEach((item) => {
72
    console.log(inspectItem(item));
73
  });
74
};
75

76
getPublishedAndDraftRecordsOfModel();

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

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

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

17

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

24

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

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, so please check there. However, you cannot use deep filtering 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)

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Dog
11
 * ├─ name: string
12
 * ├─ breed: string
13
 * ├─ age: integer
14
 * ├─ weight: float
15
 * └─ is_trained: boolean
16
 */
17

18
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
19

20
type Dog = ItemTypeDefinition<
21
  EnvironmentSettings,
22
  "GURToKAcQIyC-rTypPeHTw",
23
  {
24
    name: { type: "string" };
25
    breed: { type: "string" };
26
    age: { type: "integer" };
27
    weight: { type: "float" };
28
    is_trained: { type: "boolean" };
29
  }
30
>;
31

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

36
  const records = await client.items.list<Dog>({
37
    filter: {
38
      type: "dog",
39
      fields: {
40
        name: {
41
          in: ["Buddy", "Rex"],
42
        },
43
        breed: {
44
          eq: "mixed",
45
        },
46
        _updated_at: {
47
          gt: "2020-04-18T00:00:00",
48
        },
49
      },
50
    },
51
    order_by: "_updated_at_ASC",
52
    version: "current",
53
  });
54

55
  console.log("-- FILTERED BY FIELD VALUES --");
56
  records.forEach((item) => {
57
    console.log(inspectItem(item));
58
  });
59
}
60

61
run();

1
-- FILTERED BY FIELD VALUES --
2
└ Item "bxiqfMHRTxaB1sv4bedQTQ" (item_type: "GURToKAcQIyC-rTypPeHTw")
3
  ├ name: "Buddy"
4
  ├ breed: "mixed"
5
  ├ age: 5
6
  ├ weight: 25.5
7
  └ is_trained: true
8

9
└ Item "d9f4ZoN_T9WqJRtC-jVu_A" (item_type: "GURToKAcQIyC-rTypPeHTw")
10
  ├ name: "Rex"
11
  ├ breed: "mixed"
12
  ├ age: 3
13
  ├ weight: 30.2
14
  └ is_trained: false

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.

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.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * Dog
11
 * ├─ name: string
12
 * ├─ description: text
13
 * └─ breed: string
14
 *
15
 * Cat
16
 * ├─ name: string
17
 * ├─ description: text
18
 * └─ breed: string
19
 */
20

21
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
22

23
type Dog = ItemTypeDefinition<
24
  EnvironmentSettings,
25
  "GURToKAcQIyC-rTypPeHTw",
26
  {
27
    name: { type: "string" };
28
    description: { type: "text" };
29
    breed: { type: "string" };
30
  }
31
>;
32

33
type Cat = ItemTypeDefinition<
34
  EnvironmentSettings,
35
  "Y5l8wbEDQLKj7qm22CTucQ",
36
  {
37
    name: { type: "string" };
38
    description: { type: "text" };
39
    breed: { type: "string" };
40
  }
41
>;
42

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

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

58
  console.log("-- SEARCH RESULTS FOR 'chicken' --");
59
  records.forEach((item) => {
60
    console.log(inspectItem(item));
61
  });
62
}
63

64
run();

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

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

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

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

List all records

Response modes: Regular vs. Nested

Code

Returned output

Code

Returned output

Query parameters

Returns

Other examples

Code

Returned output

Code

Returned output

Code

Returned output

Code

Returned output

Code

Returned output

Code

Returned output

Code

Returned output