Content Management API > Record

Retrieve a record

📚 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!

To retrieve a single record, send a GET request to the /items/:id endpoint.

Response modes: Regular vs. Nested

The GET /items/:id endpoint, just like the List all records 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 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.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
5

6
  const itemId = "hWl-mnkWRYmMCSTq4z_piQ";
7

8
  const item = await client.items.find(itemId);
9

10
  // Check the 'Returned output' tab for the result ☝️
11
  console.log(item);
12
}
13

14
run();

1
{
2
  id: "hWl-mnkWRYmMCSTq4z_piQ",
3
  title: "My first blog post!",
4
  content: "Lorem ipsum dolor sit amet...",
5
  category: "24",
6
  image: {
7
    alt: "Alt text",
8
    title: "Image title",
9
    custom_data: {},
10
    focal_point: null,
11
    upload_id: "20042921",
12
  },
13
  meta: {
14
    created_at: "2020-04-21T07:57:11.124Z",
15
    updated_at: "2020-04-21T07:57:11.124Z",
16
    published_at: "2020-04-21T07:57:11.124Z",
17
    first_published_at: "2020-04-21T07:57:11.124Z",
18
    publication_scheduled_at: "2020-04-21T07:57:11.124Z",
19
    unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z",
20
    status: "published",
21
    is_current_version_valid: true,
22
    is_published_version_valid: true,
23
    current_version: "4234",
24
    stage: null,
25
    has_children: true,
26
  },
27
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
28
}

Sometimes, you may wish to fetch a record that has embedded blocks inside Modular Content, Single Block or Structured Text fields.

By default, those nested blocks are returned as block IDs (ie. "dhVR2HqgRVCTGFi_0bWqLqA"), but if you add the nested: true query parameter, we'll embed the blocks content inline for you.

1
import { buildClient } from "@datocms/cma-client-node";
2

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

7
  const records = await client.items.find("FEzWmQhjQgeHsCrUtvlEMw", {
8
    nested: true, // Retrieve its nested block content as well
9
  });
10

11
  // Instead of console.log, console.dir will fully expand nested objects
12
  // See https://nodejs.org/api/console.html#consoledirobj-options
13
  // This way, we can better see the embedded blocks in the response
14
  console.dir(records, { depth: null });
15
}
16

17
run();

1
{
2
  id: "FEzWmQhjQgeHsCrUtvlEMw",
3
  type: "item",
4
  structured_text_field: {
5
    schema: "dast",
6
    document: {
7
      children: [
8
        {
9
          item: {
10
            type: "item",
11
            attributes: {
12
              button_label: "Example button",
13
              button_url: "https://www.example.com",
14
            },
15
            relationships: {
16
              item_type: {
17
                data: { id: "SkVjHJSGR5CyK16E8TfJxg", type: "item_type" },
18
              },
19
            },
20
            id: "ahxSnFQEQ02K3TjttWAg-Q",
21
          },
22
          type: "block",
23
        },
24
        {
25
          item: {
26
            type: "item",
27
            attributes: {
28
              nested_structured_text_field: {
29
                schema: "dast",
30
                document: {
31
                  children: [
32
                    {
33
                      children: [
34
                        { type: "span", value: "This is a " },
35
                        {
36
                          marks: ["emphasis"],
37
                          type: "span",
38
                          value: "nested",
39
                        },
40
                        {
41
                          type: "span",
42
                          value: " structured text block inside the parent structured text field.",
43
                        },
44
                      ],
45
                      type: "paragraph",
46
                    },
47
                    {
48
                      item: {
49
                        type: "item",
50
                        attributes: {
51
                          button_label: "And this is a button inside the nested structured text block",
52
                          button_url: "https://www.example2.com",
53
                        },
54
                        relationships: {
55
                          item_type: {
56
                            data: {
57
                              id: "SkVjHJSGR5CyK16E8TfJxg",
58
                              type: "item_type",
59
                            },
60
                          },
61
                        },
62
                        id: "CGqwjPDsTHKGFy1IbC0RAQ",
63
                      },
64
                      type: "block",
65
                    },
66
                  ],
67
                  type: "root",
68
                },
69
              },
70
            },
71
            relationships: {
72
              item_type: {
73
                data: { id: "Ty4S40cbQH6_VMNnGdd9KA", type: "item_type" },
74
              },
75
            },
76
            id: "AppHB06oRBm-er3oooL_LA",
77
          },
78
          type: "block",
79
        },
80
      ],
81
      type: "root",
82
    },
83
  },
84
  item_type: { id: "UVa_hHEBSeefLEUnwoQFig", type: "item_type" },
85
  creator: { id: "104280", type: "account" },
86
  meta: {
87
    created_at: "2024-03-13T17:01:19.243+00:00",
88
    updated_at: "2024-03-13T17:14:17.444+00:00",
89
    published_at: "2024-03-13T17:14:17.597+00:00",
90
    publication_scheduled_at: null,
91
    unpublishing_scheduled_at: null,
92
    first_published_at: "2024-03-13T17:01:19.326+00:00",
93
    is_valid: true,
94
    is_current_version_valid: true,
95
    is_published_version_valid: true,
96
    status: "published",
97
    current_version: "DLtyHZ2MTDqYMg7g5mgYEw",
98
    stage: null,
99
  },
100
}

Query parameters

nested boolean

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

version string

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

Example:

"published"

Returns

Returns a resource object of type item

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.