Content Management API > Record

List all records

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]. You can combine it with meta fields (like _published_at, _status), but must not use model-specific fields

Example:

"c89tCUarTvGKxA37acCEWA,aCiWeOsUT3mxY0KIzUfAhw"

type string

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

Example:

"cat,dog"

query string

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.

Example:

"foo"

fields object

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: 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.

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: ?page[limit]=2page[offset]=3 (because record counting starts from 0)

1
GET https://site-api.datocms.com/items?page[limit]=2page[offset]=3 HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

To get 2 records starting from position 4, we should use: ?page[limit]=2page[offset]=3 (because record counting starts from 0)

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

To get 2 records starting from position 4, we should use: ?page[limit]=2page[offset]=3 (because record counting starts from 0)

1
await fetch("https://site-api.datocms.com/items?page[limit]=2page[offset]=3", {
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
    {
10
      "id": "VDd0Ig2WTZukQ8DU9ZskXg",
11
      "type": "item",
12
      "attributes": {
13
        "name": "Shout"
14
      },
15
      "relationships": {
16
        "item_type": {
17
          "data": {
18
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
19
            "type": "item_type"
20
          }
21
        },
22
        "creator": {
23
          "data": {
24
            "id": "254268",
25
            "type": "access_token"
26
          }
27
        }
28
      },
29
      "meta": {
30
        "created_at": "2024-03-12T20:08:33.887+00:00",
31
        "updated_at": "2024-03-12T20:08:33.895+00:00",
32
        "published_at": "2024-03-12T20:08:33.945+00:00",
33
        "publication_scheduled_at": null,
34
        "unpublishing_scheduled_at": null,
35
        "first_published_at": "2024-03-12T20:08:33.945+00:00",
36
        "is_valid": true,
37
        "is_current_version_valid": true,
38
        "is_published_version_valid": true,
39
        "status": "published",
40
        "current_version": "LPlwzflrSYyH4FQhCubRgQ",
41
        "stage": null
42
      }
43
    },
44
    {
45
      "id": "fPW3GwaCTAaCfHWr9C1RrQ",
46
      "type": "item",
47
      "attributes": {
48
        "name": "Coming Up"
49
      },
50
      "relationships": {
51
        "item_type": {
52
          "data": {
53
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
54
            "type": "item_type"
55
          }
56
        },
57
        "creator": {
58
          "data": {
59
            "id": "254268",
60
            "type": "access_token"
61
          }
62
        }
63
      },
64
      "meta": {
65
        "created_at": "2024-03-12T20:08:33.841+00:00",
66
        "updated_at": "2024-03-12T20:08:33.850+00:00",
67
        "published_at": "2024-03-12T20:08:33.882+00:00",
68
        "publication_scheduled_at": null,
69
        "unpublishing_scheduled_at": null,
70
        "first_published_at": "2024-03-12T20:08:33.882+00:00",
71
        "is_valid": true,
72
        "is_current_version_valid": true,
73
        "is_published_version_valid": true,
74
        "status": "published",
75
        "current_version": "IiCnty-tSdGnvBUZPd_g4A",
76
        "stage": null
77
      }
78
    }
79
  ],
80
  "meta": {
81
    "total_count": 264
82
  }
83
}

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

Filtering by 2 specific record IDs, across different models (one dog record, and one song record). Note that filter[ids] must be comma-separated, with no spaces.

1
GET https://site-api.datocms.com/items?filter[ids]=QHr0FFO0Ro6DtNBrFCwV0A,cSp-WX-_R7m_r_hG0D0Ekg HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

Filtering by 2 specific record IDs, across different models (one dog record, and one song record). Note that filter[ids] must be comma-separated, with no spaces.

1
curl -g 'https://site-api.datocms.com/items?filter[ids]=QHr0FFO0Ro6DtNBrFCwV0A,cSp-WX-_R7m_r_hG0D0Ekg' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

Filtering by 2 specific record IDs, across different models (one dog record, and one song record). Note that filter[ids] must be comma-separated, with no spaces.

1
await fetch(
2
  "https://site-api.datocms.com/items?filter[ids]=QHr0FFO0Ro6DtNBrFCwV0A,cSp-WX-_R7m_r_hG0D0Ekg",
3
  {
4
    headers: {
5
      Authorization: "Bearer YOUR-API-TOKEN",
6
      Accept: "application/json",
7
      "X-Api-Version": "3",
8
    },
9
  },
10
);

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
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
    {
10
      "id": "cSp-WX-_R7m_r_hG0D0Ekg",
11
      "type": "item",
12
      "attributes": {
13
        "name": "One of Us"
14
      },
15
      "relationships": {
16
        "item_type": {
17
          "data": {
18
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
19
            "type": "item_type"
20
          }
21
        },
22
        "creator": {
23
          "data": {
24
            "id": "254268",
25
            "type": "access_token"
26
          }
27
        }
28
      },
29
      "meta": {
30
        "created_at": "2024-03-12T20:08:33.743+00:00",
31
        "updated_at": "2024-03-12T20:08:33.755+00:00",
32
        "published_at": "2024-03-12T20:08:34.240+00:00",
33
        "publication_scheduled_at": null,
34
        "unpublishing_scheduled_at": null,
35
        "first_published_at": "2024-03-12T20:08:34.240+00:00",
36
        "is_valid": true,
37
        "is_current_version_valid": true,
38
        "is_published_version_valid": true,
39
        "status": "published",
40
        "current_version": "SjWxQjSCRy-g_B7t1GcnPw",
41
        "stage": null
42
      }
43
    },
44
    {
45
      "id": "QHr0FFO0Ro6DtNBrFCwV0A",
46
      "type": "item",
47
      "attributes": {
48
        "name": "Maji",
49
        "breed": "mixed"
50
      },
51
      "relationships": {
52
        "item_type": {
53
          "data": {
54
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
55
            "type": "item_type"
56
          }
57
        },
58
        "creator": {
59
          "data": {
60
            "id": "104280",
61
            "type": "account"
62
          }
63
        }
64
      },
65
      "meta": {
66
        "created_at": "2024-01-26T20:24:36.462+00:00",
67
        "updated_at": "2024-01-26T20:24:36.618+00:00",
68
        "published_at": "2024-01-26T20:24:36.779+00:00",
69
        "publication_scheduled_at": null,
70
        "unpublishing_scheduled_at": null,
71
        "first_published_at": "2024-01-26T20:24:36.779+00:00",
72
        "is_valid": true,
73
        "is_current_version_valid": true,
74
        "is_published_version_valid": true,
75
        "status": "published",
76
        "current_version": "YmES_iXOT3GguMQXoFZcWw",
77
        "stage": null
78
      }
79
    }
80
  ],
81
  "meta": {
82
    "total_count": 2
83
  }
84
}

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:

Filtering by the model with api_key cat and the model with ID of dog:

1
GET https://site-api.datocms.com/items?filter[type]=cat,MtzQYUvbS-S0LM2LZ5QlkQ HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

Filtering by the model with api_key cat and the model with ID of dog:

1
curl -g 'https://site-api.datocms.com/items?filter[type]=cat,MtzQYUvbS-S0LM2LZ5QlkQ' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

Filtering by the model with api_key cat and the model with ID of dog:

1
await fetch(
2
  "https://site-api.datocms.com/items?filter[type]=cat,MtzQYUvbS-S0LM2LZ5QlkQ",
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
{
8
  "data": [
9
    {
10
      "id": "QHr0FFO0Ro6DtNBrFCwV0A",
11
      "type": "item",
12
      "attributes": {
13
        "name": "Maji",
14
        "breed": "mixed"
15
      },
16
      "relationships": {
17
        "item_type": {
18
          "data": {
19
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
20
            "type": "item_type"
21
          }
22
        },
23
        "creator": {
24
          "data": {
25
            "id": "104280",
26
            "type": "account"
27
          }
28
        }
29
      },
30
      "meta": {
31
        "created_at": "2024-01-26T20:24:36.462+00:00",
32
        "updated_at": "2024-01-26T20:24:36.618+00:00",
33
        "published_at": "2024-01-26T20:24:36.779+00:00",
34
        "publication_scheduled_at": null,
35
        "unpublishing_scheduled_at": null,
36
        "first_published_at": "2024-01-26T20:24:36.779+00:00",
37
        "is_valid": true,
38
        "is_current_version_valid": true,
39
        "is_published_version_valid": true,
40
        "status": "published",
41
        "current_version": "YmES_iXOT3GguMQXoFZcWw",
42
        "stage": null
43
      }
44
    },
45
    {
46
      "id": "RGLUGlQiTKiAQuB3D9C_1g",
47
      "type": "item",
48
      "attributes": {
49
        "name": "Higgins",
50
        "breed": "hovawart"
51
      },
52
      "relationships": {
53
        "item_type": {
54
          "data": {
55
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
56
            "type": "item_type"
57
          }
58
        },
59
        "creator": {
60
          "data": {
61
            "id": "104280",
62
            "type": "account"
63
          }
64
        }
65
      },
66
      "meta": {
67
        "created_at": "2024-01-26T20:23:49.239+00:00",
68
        "updated_at": "2024-01-26T20:23:49.247+00:00",
69
        "published_at": "2024-01-26T20:23:49.267+00:00",
70
        "publication_scheduled_at": null,
71
        "unpublishing_scheduled_at": null,
72
        "first_published_at": "2024-01-26T20:23:49.267+00:00",
73
        "is_valid": true,
74
        "is_current_version_valid": true,
75
        "is_published_version_valid": true,
76
        "status": "published",
77
        "current_version": "WvWbSB9iQfG8o2mg_f5K5A",
78
        "stage": null
79
      }
80
    }
81
  ],
82
  "meta": {
83
    "total_count": 2
84
  }
85
}

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)

Note the special handling of the in filter for the name field. Instead of a comma-separated string, it's two separate [fields][name][in][] parameters.

1
GET https://site-api.datocms.com/items?filter[type]=dog&filter[fields][name][in][]=Buddy&filter[fields][name][in][]=Rex&filter[fields][breed][eq]=mixed&filter[fields][_updated_at][gt]=2020-04-18T00:00:00&order_by=_updated_at_ASC HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

Note the special handling of the in filter for the name field. Instead of a comma-separated string, it's two separate [fields][name][in][] parameters.

1
curl -g 'https://site-api.datocms.com/items?filter[type]=dog&filter[fields][name][in][]=Buddy&filter[fields][name][in][]=Rex&filter[fields][breed][eq]=mixed&filter[fields][_updated_at][gt]=2020-04-18T00:00:00&order_by=_updated_at_ASC' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

Note the special handling of the in filter for the name field. Instead of a comma-separated string, it's two separate [fields][name][in][] parameters.

1
await fetch(
2
  "https://site-api.datocms.com/items?filter[type]=dog&filter[fields][name][in][]=Buddy&filter[fields][name][in][]=Rex&filter[fields][breed][eq]=mixed&filter[fields][_updated_at][gt]=2020-04-18T00:00:00&order_by=_updated_at_ASC",
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
{
8
  "data": [
9
    {
10
      "id": "EA4kSeoVQqKSR88cVq2kqQ",
11
      "type": "item",
12
      "attributes": {
13
        "name": "Rex",
14
        "breed": "mixed"
15
      },
16
      "relationships": {
17
        "item_type": {
18
          "data": {
19
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
20
            "type": "item_type"
21
          }
22
        },
23
        "creator": {
24
          "data": {
25
            "id": "104280",
26
            "type": "account"
27
          }
28
        }
29
      },
30
      "meta": {
31
        "created_at": "2024-03-12T22:30:44.137+00:00",
32
        "updated_at": "2024-03-12T22:30:44.146+00:00",
33
        "published_at": "2024-03-12T22:30:44.178+00:00",
34
        "publication_scheduled_at": null,
35
        "unpublishing_scheduled_at": null,
36
        "first_published_at": "2024-03-12T22:30:44.178+00:00",
37
        "is_valid": true,
38
        "is_current_version_valid": true,
39
        "is_published_version_valid": true,
40
        "status": "published",
41
        "current_version": "QIjEZ8glRkix0gt9uz0Pfg",
42
        "stage": null
43
      }
44
    },
45
    {
46
      "id": "B1E0yYBORgmRpa_oK5LrOw",
47
      "type": "item",
48
      "attributes": {
49
        "name": "Buddy",
50
        "breed": "mixed"
51
      },
52
      "relationships": {
53
        "item_type": {
54
          "data": {
55
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
56
            "type": "item_type"
57
          }
58
        },
59
        "creator": {
60
          "data": {
61
            "id": "104280",
62
            "type": "account"
63
          }
64
        }
65
      },
66
      "meta": {
67
        "created_at": "2024-01-30T00:11:04.310+00:00",
68
        "updated_at": "2024-03-12T22:31:26.455+00:00",
69
        "published_at": "2024-03-12T22:31:26.491+00:00",
70
        "publication_scheduled_at": null,
71
        "unpublishing_scheduled_at": null,
72
        "first_published_at": "2024-01-30T00:11:04.340+00:00",
73
        "is_valid": true,
74
        "is_current_version_valid": true,
75
        "is_published_version_valid": true,
76
        "status": "published",
77
        "current_version": "KhshsDnyRVi3aMzBBs7QMQ",
78
        "stage": null
79
      }
80
    }
81
  ],
82
  "meta": {
83
    "total_count": 2
84
  }
85
}

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
GET https://site-api.datocms.com/items?filter[type]=dog,cat&filter[query]=chicken&locale=en&order_by=_rank_DESC 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?filter[type]=dog,cat&filter[query]=chicken&locale=en&order_by=_rank_DESC' \
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?filter[type]=dog,cat&filter[query]=chicken&locale=en&order_by=_rank_DESC",
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
{
8
  "data": [
9
    {
10
      "id": "B1E0yYBORgmRpa_oK5LrOw",
11
      "type": "item",
12
      "attributes": {
13
        "name": "Buddy",
14
        "breed": "mixed",
15
        "description": "Buddy loves chicken. Just make sure it's cooked and doesn't have any seasonings or bones!"
16
      },
17
      "relationships": {
18
        "item_type": {
19
          "data": {
20
            "id": "MtzQYUvbS-S0LM2LZ5QlkQ",
21
            "type": "item_type"
22
          }
23
        },
24
        "creator": {
25
          "data": {
26
            "id": "104280",
27
            "type": "account"
28
          }
29
        }
30
      },
31
      "meta": {
32
        "created_at": "2024-01-30T00:11:04.310+00:00",
33
        "updated_at": "2024-03-12T22:31:26.455+00:00",
34
        "published_at": "2024-03-12T22:31:26.491+00:00",
35
        "publication_scheduled_at": null,
36
        "unpublishing_scheduled_at": null,
37
        "first_published_at": "2024-01-30T00:11:04.340+00:00",
38
        "is_valid": true,
39
        "is_current_version_valid": true,
40
        "is_published_version_valid": true,
41
        "status": "published",
42
        "current_version": "KhshsDnyRVi3aMzBBs7QMQ",
43
        "stage": null
44
      }
45
    },
46
    {
47
      "id": "c89tCUarTvGKxA37acCEWA",
48
      "type": "item",
49
      "attributes": {
50
        "name": "Sheriff",
51
        "breed": "domestic_longhair",
52
        "description": "Sheriff loves salmon, sweet potatoes and chicken."
53
      },
54
      "relationships": {
55
        "item_type": {
56
          "data": {
57
            "id": "JwCG35JtS_y92WZoOq1Ujw",
58
            "type": "item_type"
59
          }
60
        },
61
        "creator": {
62
          "data": {
63
            "id": "104280",
64
            "type": "account"
65
          }
66
        }
67
      },
68
      "meta": {
69
        "created_at": "2024-01-26T20:23:31.721+00:00",
70
        "updated_at": "2024-01-30T00:24:16.370+00:00",
71
        "published_at": "2024-01-30T00:24:16.393+00:00",
72
        "publication_scheduled_at": null,
73
        "unpublishing_scheduled_at": null,
74
        "first_published_at": "2024-01-26T20:23:31.752+00:00",
75
        "is_valid": true,
76
        "is_current_version_valid": true,
77
        "is_published_version_valid": true,
78
        "status": "published",
79
        "current_version": "Uh_nr0kWRZy54W91MWrdLg",
80
        "stage": null
81
      }
82
    }
83
  ],
84
  "meta": {
85
    "total_count": 2
86
  }
87
}

List all records

Query parameters

Returns

Other examples

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response