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
GET https://site-api.datocms.com/items/:item_id HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

1
curl -g 'https://site-api.datocms.com/items/:item_id' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

1
await fetch("https://site-api.datocms.com/items/:item_id", {
2
  headers: {
3
    Authorization: "Bearer YOUR-API-TOKEN",
4
    Accept: "application/json",
5
    "X-Api-Version": "3",
6
  },
7
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "item",
10
    "id": "hWl-mnkWRYmMCSTq4z_piQ",
11
    "relationships": {
12
      "item_type": {
13
        "data": {
14
          "type": "item_type",
15
          "id": "DxMaW10UQiCmZcuuA-IkkA"
16
        }
17
      }
18
    },
19
    "attributes": {
20
      "title": "My first blog post!",
21
      "content": "Lorem ipsum dolor sit amet...",
22
      "category": "24",
23
      "image": {
24
        "alt": "Alt text",
25
        "title": "Image title",
26
        "custom_data": {},
27
        "focal_point": null,
28
        "upload_id": "20042921"
29
      }
30
    },
31
    "meta": {
32
      "created_at": "2020-04-21T07:57:11.124Z",
33
      "updated_at": "2020-04-21T07:57:11.124Z",
34
      "published_at": "2020-04-21T07:57:11.124Z",
35
      "first_published_at": "2020-04-21T07:57:11.124Z",
36
      "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
37
      "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
38
      "status": "published",
39
      "is_current_version_valid": true,
40
      "is_published_version_valid": true,
41
      "current_version": "4234",
42
      "stage": null,
43
      "has_children": true
44
    }
45
  }
46
}

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
GET https://site-api.datocms.com/items/FEzWmQhjQgeHsCrUtvlEMw?nested=true HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

1
curl -g 'https://site-api.datocms.com/items/FEzWmQhjQgeHsCrUtvlEMw?nested=true' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

1
await fetch(
2
  "https://site-api.datocms.com/items/FEzWmQhjQgeHsCrUtvlEMw?nested=true",
3
  {
4
    headers: {
5
      Authorization: "Bearer YOUR-API-TOKEN",
6
      Accept: "application/json",
7
      "X-Api-Version": "3",
8
    },
9
  },
10
);

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
-- Regular mode --
8
└ Item "FEzWmQhjQgeHsCrUtvlEMw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
9
  ├ title: "My first blog post!"
10
  └ sections
11
    └ [0]: "Mpgkz94PQsiV8vmvpIS4oA"
12

13
-- Nested mode --
14
└ Item "FEzWmQhjQgeHsCrUtvlEMw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
15
  ├ title: "My first blog post!"
16
  └ sections
17
    └ [0] Item "Mpgkz94PQsiV8vmvpIS4oA" (item_type: "T4m4tPymSACFzsqbZS65WA")
18
      └ headline: "Welcome to the example!"

TypeScript typing

Reading a record without typed schemas means every attribute comes back as unknown, and the IDE can't help you navigate it. The single biggest lever you have is passing a generated Schema.X marker as the generic on items.find. TypeScript then knows the exact shape of the returned record — its field names, types, and block structures — so reads are typed end-to-end:

1
import * as Schema from "./schema";
2

3
const record = await client.items.find<Schema.Article>("record-id");
4
record.title; // typed, not unknown

For the exact type of a specific field on the returned record (to annotate a helper or intermediate variable), index ApiTypes.Item<Schema.Article>["field_api_key"] (or ApiTypes.ItemInNestedResponse<Schema.Article>["field_api_key"] when fetching with nested: true). See the full TypeScript guide for how to generate schema.ts and the complete pattern.

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) of your records, or the latest available (current, default)

Example:

"published"

Returns

Returns a resource object of type item.

Retrieve a record

Response modes: Regular vs. Nested

HTTP Request

CURL Request

fetch() Request