Show examples in:

Endpoint info

Returns

Available examples

Basic example: Fetching records

Fetching a specific page of records

Fetching records by their IDs

Fetching records belonging to a model

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

Fetching records by a textual generic query

Fetching nested blocks in a record

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!

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

Pro tip: in case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the Content Management API as well!

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

If you don't specify any parameters, we'll simply return the first 30 records. They can be from any model in your project.

1
GET https://site-api.datocms.com/items 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' \
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", {
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
      "id": "N_-eUO9JQYGaaglCwQSWog",
81
      "type": "item",
82
      "attributes": {
83
        "name": "Help Me"
84
      },
85
      "relationships": {
86
        "item_type": {
87
          "data": {
88
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
89
            "type": "item_type"
90
          }
91
        },
92
        "creator": {
93
          "data": {
94
            "id": "254268",
95
            "type": "access_token"
96
          }
97
        }
98
      },
99
      "meta": {
100
        "created_at": "2024-03-12T20:08:33.822+00:00",
101
        "updated_at": "2024-03-12T20:08:33.829+00:00",
102
        "published_at": "2024-03-12T20:08:33.855+00:00",
103
        "publication_scheduled_at": null,
104
        "unpublishing_scheduled_at": null,
105
        "first_published_at": "2024-03-12T20:08:33.855+00:00",
106
        "is_valid": true,
107
        "is_current_version_valid": true,
108
        "is_published_version_valid": true,
109
        "status": "published",
110
        "current_version": "OBGHUfjgQzWyTiBZ3S0ZxA",
111
        "stage": null
112
      }
113
    },
114
    {
115
      "id": "QzIMNNYARMiT7mXQffJXUw",
116
      "type": "item",
117
      "attributes": {
118
        "name": "Revolution"
119
      },
120
      "relationships": {
121
        "item_type": {
122
          "data": {
123
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
124
            "type": "item_type"
125
          }
126
        },
127
        "creator": {
128
          "data": {
129
            "id": "254268",
130
            "type": "access_token"
131
          }
132
        }
133
      },
134
      "meta": {
135
        "created_at": "2024-03-12T20:08:33.755+00:00",
136
        "updated_at": "2024-03-12T20:08:33.790+00:00",
137
        "published_at": "2024-03-12T20:08:33.888+00:00",
138
        "publication_scheduled_at": null,
139
        "unpublishing_scheduled_at": null,
140
        "first_published_at": "2024-03-12T20:08:33.888+00:00",
141
        "is_valid": true,
142
        "is_current_version_valid": true,
143
        "is_published_version_valid": true,
144
        "status": "published",
145
        "current_version": "UM3T3zlISyKWp3lAethauA",
146
        "stage": null
147
      }
148
    },
149
    {
150
      "id": "cSp-WX-_R7m_r_hG0D0Ekg",
151
      "type": "item",
152
      "attributes": {
153
        "name": "One of Us"
154
      },
155
      "relationships": {
156
        "item_type": {
157
          "data": {
158
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
159
            "type": "item_type"
160
          }
161
        },
162
        "creator": {
163
          "data": {
164
            "id": "254268",
165
            "type": "access_token"
166
          }
167
        }
168
      },
169
      "meta": {
170
        "created_at": "2024-03-12T20:08:33.743+00:00",
171
        "updated_at": "2024-03-12T20:08:33.755+00:00",
172
        "published_at": "2024-03-12T20:08:34.240+00:00",
173
        "publication_scheduled_at": null,
174
        "unpublishing_scheduled_at": null,
175
        "first_published_at": "2024-03-12T20:08:34.240+00:00",
176
        "is_valid": true,
177
        "is_current_version_valid": true,
178
        "is_published_version_valid": true,
179
        "status": "published",
180
        "current_version": "SjWxQjSCRy-g_B7t1GcnPw",
181
        "stage": null
182
      }
183
    },
184
    {
185
      "id": "Se50jCOWT5SOghV3onN6Mw",
186
      "type": "item",
187
      "attributes": {
188
        "name": "Sweet Child O' Mine"
189
      },
190
      "relationships": {
191
        "item_type": {
192
          "data": {
193
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
194
            "type": "item_type"
195
          }
196
        },
197
        "creator": {
198
          "data": {
199
            "id": "254268",
200
            "type": "access_token"
201
          }
202
        }
203
      },
204
      "meta": {
205
        "created_at": "2024-03-12T20:08:33.719+00:00",
206
        "updated_at": "2024-03-12T20:08:33.747+00:00",
207
        "published_at": "2024-03-12T20:08:33.924+00:00",
208
        "publication_scheduled_at": null,
209
        "unpublishing_scheduled_at": null,
210
        "first_published_at": "2024-03-12T20:08:33.924+00:00",
211
        "is_valid": true,
212
        "is_current_version_valid": true,
213
        "is_published_version_valid": true,
214
        "status": "published",
215
        "current_version": "TVRARw0hSt6hUiQvLv2ang",
216
        "stage": null
217
      }
218
    },
219
    {
220
      "id": "fbR0-_4QTHqJmJia2h16Rw",
221
      "type": "item",
222
      "attributes": {
223
        "name": "Mmmbop"
224
      },
225
      "relationships": {
226
        "item_type": {
227
          "data": {
228
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
229
            "type": "item_type"
230
          }
231
        },
232
        "creator": {
233
          "data": {
234
            "id": "254268",
235
            "type": "access_token"
236
          }
237
        }
238
      },
239
      "meta": {
240
        "created_at": "2024-03-12T20:08:33.720+00:00",
241
        "updated_at": "2024-03-12T20:08:33.743+00:00",
242
        "published_at": "2024-03-12T20:08:33.911+00:00",
243
        "publication_scheduled_at": null,
244
        "unpublishing_scheduled_at": null,
245
        "first_published_at": "2024-03-12T20:08:33.911+00:00",
246
        "is_valid": true,
247
        "is_current_version_valid": true,
248
        "is_published_version_valid": true,
249
        "status": "published",
250
        "current_version": "Bz6Q2sN9SReSkExNVmtsbg",
251
        "stage": null
252
      }
253
    },
254
    {
255
      "id": "PDsVV3r_QB2svx1kUF8Rpg",
256
      "type": "item",
257
      "attributes": {
258
        "name": "Sexyback"
259
      },
260
      "relationships": {
261
        "item_type": {
262
          "data": {
263
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
264
            "type": "item_type"
265
          }
266
        },
267
        "creator": {
268
          "data": {
269
            "id": "254268",
270
            "type": "access_token"
271
          }
272
        }
273
      },
274
      "meta": {
275
        "created_at": "2024-03-12T20:08:33.700+00:00",
276
        "updated_at": "2024-03-12T20:08:33.741+00:00",
277
        "published_at": "2024-03-12T20:08:33.805+00:00",
278
        "publication_scheduled_at": null,
279
        "unpublishing_scheduled_at": null,
280
        "first_published_at": "2024-03-12T20:08:33.805+00:00",
281
        "is_valid": true,
282
        "is_current_version_valid": true,
283
        "is_published_version_valid": true,
284
        "status": "published",
285
        "current_version": "GSzCoAaRQEiT7QuRGHwFjg",
286
        "stage": null
287
      }
288
    },
289
    {
290
      "id": "RIBJJQMSS5eXJwGxbifYHw",
291
      "type": "item",
292
      "attributes": {
293
        "name": "Disturbia"
294
      },
295
      "relationships": {
296
        "item_type": {
297
          "data": {
298
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
299
            "type": "item_type"
300
          }
301
        },
302
        "creator": {
303
          "data": {
304
            "id": "254268",
305
            "type": "access_token"
306
          }
307
        }
308
      },
309
      "meta": {
310
        "created_at": "2024-03-12T20:08:33.720+00:00",
311
        "updated_at": "2024-03-12T20:08:33.734+00:00",
312
        "published_at": "2024-03-12T20:08:33.784+00:00",
313
        "publication_scheduled_at": null,
314
        "unpublishing_scheduled_at": null,
315
        "first_published_at": "2024-03-12T20:08:33.784+00:00",
316
        "is_valid": true,
317
        "is_current_version_valid": true,
318
        "is_published_version_valid": true,
319
        "status": "published",
320
        "current_version": "V9c7_0jCSWOX8RWVMQGUwg",
321
        "stage": null
322
      }
323
    },
324
    {
325
      "id": "Ieuj8bvVRSu9mwMveGSwXw",
326
      "type": "item",
327
      "attributes": {
328
        "name": "Freak Me"
329
      },
330
      "relationships": {
331
        "item_type": {
332
          "data": {
333
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
334
            "type": "item_type"
335
          }
336
        },
337
        "creator": {
338
          "data": {
339
            "id": "254268",
340
            "type": "access_token"
341
          }
342
        }
343
      },
344
      "meta": {
345
        "created_at": "2024-03-12T20:08:33.706+00:00",
346
        "updated_at": "2024-03-12T20:08:33.713+00:00",
347
        "published_at": "2024-03-12T20:08:33.734+00:00",
348
        "publication_scheduled_at": null,
349
        "unpublishing_scheduled_at": null,
350
        "first_published_at": "2024-03-12T20:08:33.734+00:00",
351
        "is_valid": true,
352
        "is_current_version_valid": true,
353
        "is_published_version_valid": true,
354
        "status": "published",
355
        "current_version": "dstkWckSQgauGwRlDIUBwA",
356
        "stage": null
357
      }
358
    },
359
    {
360
      "id": "TbI1PkaNR0e3LFcw6Ckmog",
361
      "type": "item",
362
      "attributes": {
363
        "name": "Kiss & Say Goodbye"
364
      },
365
      "relationships": {
366
        "item_type": {
367
          "data": {
368
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
369
            "type": "item_type"
370
          }
371
        },
372
        "creator": {
373
          "data": {
374
            "id": "254268",
375
            "type": "access_token"
376
          }
377
        }
378
      },
379
      "meta": {
380
        "created_at": "2024-03-12T20:08:33.641+00:00",
381
        "updated_at": "2024-03-12T20:08:33.705+00:00",
382
        "published_at": "2024-03-12T20:08:33.773+00:00",
383
        "publication_scheduled_at": null,
384
        "unpublishing_scheduled_at": null,
385
        "first_published_at": "2024-03-12T20:08:33.773+00:00",
386
        "is_valid": true,
387
        "is_current_version_valid": true,
388
        "is_published_version_valid": true,
389
        "status": "published",
390
        "current_version": "IGCN5mkFRp-tnZxxZ_a9lA",
391
        "stage": null
392
      }
393
    },
394
    {
395
      "id": "c8J1VJ_OSySn_QBW-hHahw",
396
      "type": "item",
397
      "attributes": {
398
        "name": "Nothing Compares 2 U"
399
      },
400
      "relationships": {
401
        "item_type": {
402
          "data": {
403
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
404
            "type": "item_type"
405
          }
406
        },
407
        "creator": {
408
          "data": {
409
            "id": "254268",
410
            "type": "access_token"
411
          }
412
        }
413
      },
414
      "meta": {
415
        "created_at": "2024-03-12T20:08:33.639+00:00",
416
        "updated_at": "2024-03-12T20:08:33.649+00:00",
417
        "published_at": "2024-03-12T20:08:33.705+00:00",
418
        "publication_scheduled_at": null,
419
        "unpublishing_scheduled_at": null,
420
        "first_published_at": "2024-03-12T20:08:33.705+00:00",
421
        "is_valid": true,
422
        "is_current_version_valid": true,
423
        "is_published_version_valid": true,
424
        "status": "published",
425
        "current_version": "TIKPdgkIT9aupLazDwczAg",
426
        "stage": null
427
      }
428
    },
429
    {
430
      "id": "KhMoyywXQ3m3tpegrsh6VQ",
431
      "type": "item",
432
      "attributes": {
433
        "name": "Here Without You"
434
      },
435
      "relationships": {
436
        "item_type": {
437
          "data": {
438
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
439
            "type": "item_type"
440
          }
441
        },
442
        "creator": {
443
          "data": {
444
            "id": "254268",
445
            "type": "access_token"
446
          }
447
        }
448
      },
449
      "meta": {
450
        "created_at": "2024-03-12T20:08:33.564+00:00",
451
        "updated_at": "2024-03-12T20:08:33.577+00:00",
452
        "published_at": "2024-03-12T20:08:33.611+00:00",
453
        "publication_scheduled_at": null,
454
        "unpublishing_scheduled_at": null,
455
        "first_published_at": "2024-03-12T20:08:33.611+00:00",
456
        "is_valid": true,
457
        "is_current_version_valid": true,
458
        "is_published_version_valid": true,
459
        "status": "published",
460
        "current_version": "fwFBPaVGRrulUy0PWjGmFw",
461
        "stage": null
462
      }
463
    },
464
    {
465
      "id": "Qje_l1cnSmu5baRVOFw7gQ",
466
      "type": "item",
467
      "attributes": {
468
        "name": "Lights"
469
      },
470
      "relationships": {
471
        "item_type": {
472
          "data": {
473
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
474
            "type": "item_type"
475
          }
476
        },
477
        "creator": {
478
          "data": {
479
            "id": "254268",
480
            "type": "access_token"
481
          }
482
        }
483
      },
484
      "meta": {
485
        "created_at": "2024-03-12T20:08:33.549+00:00",
486
        "updated_at": "2024-03-12T20:08:33.558+00:00",
487
        "published_at": "2024-03-12T20:08:33.586+00:00",
488
        "publication_scheduled_at": null,
489
        "unpublishing_scheduled_at": null,
490
        "first_published_at": "2024-03-12T20:08:33.586+00:00",
491
        "is_valid": true,
492
        "is_current_version_valid": true,
493
        "is_published_version_valid": true,
494
        "status": "published",
495
        "current_version": "XucCRmJGQLKwc-N_ng47zQ",
496
        "stage": null
497
      }
498
    },
499
    {
500
      "id": "PYJxVcctSiSM5XeSynv_1Q",
501
      "type": "item",
502
      "attributes": {
503
        "name": "Another Brick in the Wall (part 2)"
504
      },
505
      "relationships": {
506
        "item_type": {
507
          "data": {
508
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
509
            "type": "item_type"
510
          }
511
        },
512
        "creator": {
513
          "data": {
514
            "id": "254268",
515
            "type": "access_token"
516
          }
517
        }
518
      },
519
      "meta": {
520
        "created_at": "2024-03-12T20:08:33.542+00:00",
521
        "updated_at": "2024-03-12T20:08:33.551+00:00",
522
        "published_at": "2024-03-12T20:08:33.590+00:00",
523
        "publication_scheduled_at": null,
524
        "unpublishing_scheduled_at": null,
525
        "first_published_at": "2024-03-12T20:08:33.590+00:00",
526
        "is_valid": true,
527
        "is_current_version_valid": true,
528
        "is_published_version_valid": true,
529
        "status": "published",
530
        "current_version": "TDODGE4FTc2G43E162qGOg",
531
        "stage": null
532
      }
533
    },
534
    {
535
      "id": "J1yFGsVRQi-m15gNcF8P6A",
536
      "type": "item",
537
      "attributes": {
538
        "name": "Nights in White Satin"
539
      },
540
      "relationships": {
541
        "item_type": {
542
          "data": {
543
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
544
            "type": "item_type"
545
          }
546
        },
547
        "creator": {
548
          "data": {
549
            "id": "254268",
550
            "type": "access_token"
551
          }
552
        }
553
      },
554
      "meta": {
555
        "created_at": "2024-03-12T20:08:33.531+00:00",
556
        "updated_at": "2024-03-12T20:08:33.537+00:00",
557
        "published_at": "2024-03-12T20:08:33.557+00:00",
558
        "publication_scheduled_at": null,
559
        "unpublishing_scheduled_at": null,
560
        "first_published_at": "2024-03-12T20:08:33.557+00:00",
561
        "is_valid": true,
562
        "is_current_version_valid": true,
563
        "is_published_version_valid": true,
564
        "status": "published",
565
        "current_version": "UjxUj6lVTwW24f4hRQ4tmQ",
566
        "stage": null
567
      }
568
    },
569
    {
570
      "id": "aSvm-MvUQ5uxUNh_WKq3Zw",
571
      "type": "item",
572
      "attributes": {
573
        "name": "Mr Big Stuff"
574
      },
575
      "relationships": {
576
        "item_type": {
577
          "data": {
578
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
579
            "type": "item_type"
580
          }
581
        },
582
        "creator": {
583
          "data": {
584
            "id": "254268",
585
            "type": "access_token"
586
          }
587
        }
588
      },
589
      "meta": {
590
        "created_at": "2024-03-12T20:08:32.047+00:00",
591
        "updated_at": "2024-03-12T20:08:32.353+00:00",
592
        "published_at": "2024-03-12T20:08:33.190+00:00",
593
        "publication_scheduled_at": null,
594
        "unpublishing_scheduled_at": null,
595
        "first_published_at": "2024-03-12T20:08:33.190+00:00",
596
        "is_valid": true,
597
        "is_current_version_valid": true,
598
        "is_published_version_valid": true,
599
        "status": "published",
600
        "current_version": "PvAQQ8a4TL2UalPgz28T6Q",
601
        "stage": null
602
      }
603
    },
604
    {
605
      "id": "PaawsjZoTV-ntkDYKXdnDQ",
606
      "type": "item",
607
      "attributes": {
608
        "name": "Puttin' on the Ritz"
609
      },
610
      "relationships": {
611
        "item_type": {
612
          "data": {
613
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
614
            "type": "item_type"
615
          }
616
        },
617
        "creator": {
618
          "data": {
619
            "id": "254268",
620
            "type": "access_token"
621
          }
622
        }
623
      },
624
      "meta": {
625
        "created_at": "2024-03-12T20:08:30.907+00:00",
626
        "updated_at": "2024-03-12T20:08:30.914+00:00",
627
        "published_at": "2024-03-12T20:08:30.940+00:00",
628
        "publication_scheduled_at": null,
629
        "unpublishing_scheduled_at": null,
630
        "first_published_at": "2024-03-12T20:08:30.940+00:00",
631
        "is_valid": true,
632
        "is_current_version_valid": true,
633
        "is_published_version_valid": true,
634
        "status": "published",
635
        "current_version": "CzJ-blM8TRCy4YERcFscCQ",
636
        "stage": null
637
      }
638
    },
639
    {
640
      "id": "aTGstd4dR2GZmqziBae1Ng",
641
      "type": "item",
642
      "attributes": {
643
        "name": "Give Me Everything"
644
      },
645
      "relationships": {
646
        "item_type": {
647
          "data": {
648
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
649
            "type": "item_type"
650
          }
651
        },
652
        "creator": {
653
          "data": {
654
            "id": "254268",
655
            "type": "access_token"
656
          }
657
        }
658
      },
659
      "meta": {
660
        "created_at": "2024-03-12T20:08:30.896+00:00",
661
        "updated_at": "2024-03-12T20:08:30.904+00:00",
662
        "published_at": "2024-03-12T20:08:30.933+00:00",
663
        "publication_scheduled_at": null,
664
        "unpublishing_scheduled_at": null,
665
        "first_published_at": "2024-03-12T20:08:30.933+00:00",
666
        "is_valid": true,
667
        "is_current_version_valid": true,
668
        "is_published_version_valid": true,
669
        "status": "published",
670
        "current_version": "JMgMTVGpSeq9a_RdMQUvPA",
671
        "stage": null
672
      }
673
    },
674
    {
675
      "id": "XeyHPBhRQuyPnF5MqJeFIw",
676
      "type": "item",
677
      "attributes": {
678
        "name": "Brother Louie"
679
      },
680
      "relationships": {
681
        "item_type": {
682
          "data": {
683
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
684
            "type": "item_type"
685
          }
686
        },
687
        "creator": {
688
          "data": {
689
            "id": "254268",
690
            "type": "access_token"
691
          }
692
        }
693
      },
694
      "meta": {
695
        "created_at": "2024-03-12T20:08:30.893+00:00",
696
        "updated_at": "2024-03-12T20:08:30.900+00:00",
697
        "published_at": "2024-03-12T20:08:30.932+00:00",
698
        "publication_scheduled_at": null,
699
        "unpublishing_scheduled_at": null,
700
        "first_published_at": "2024-03-12T20:08:30.932+00:00",
701
        "is_valid": true,
702
        "is_current_version_valid": true,
703
        "is_published_version_valid": true,
704
        "status": "published",
705
        "current_version": "DZoZPfKxTpiAv4daOfpWoQ",
706
        "stage": null
707
      }
708
    },
709
    {
710
      "id": "PnE_1FRNQSGNOaKsPSAeVA",
711
      "type": "item",
712
      "attributes": {
713
        "name": "Check On It"
714
      },
715
      "relationships": {
716
        "item_type": {
717
          "data": {
718
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
719
            "type": "item_type"
720
          }
721
        },
722
        "creator": {
723
          "data": {
724
            "id": "254268",
725
            "type": "access_token"
726
          }
727
        }
728
      },
729
      "meta": {
730
        "created_at": "2024-03-12T20:08:30.838+00:00",
731
        "updated_at": "2024-03-12T20:08:30.846+00:00",
732
        "published_at": "2024-03-12T20:08:30.878+00:00",
733
        "publication_scheduled_at": null,
734
        "unpublishing_scheduled_at": null,
735
        "first_published_at": "2024-03-12T20:08:30.878+00:00",
736
        "is_valid": true,
737
        "is_current_version_valid": true,
738
        "is_published_version_valid": true,
739
        "status": "published",
740
        "current_version": "e7x9KwfLRPmJgn6Vgl_E1g",
741
        "stage": null
742
      }
743
    },
744
    {
745
      "id": "Bmrj1Q_DT-y0HvdAEzzsug",
746
      "type": "item",
747
      "attributes": {
748
        "name": "The End of the World"
749
      },
750
      "relationships": {
751
        "item_type": {
752
          "data": {
753
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
754
            "type": "item_type"
755
          }
756
        },
757
        "creator": {
758
          "data": {
759
            "id": "254268",
760
            "type": "access_token"
761
          }
762
        }
763
      },
764
      "meta": {
765
        "created_at": "2024-03-12T20:08:30.638+00:00",
766
        "updated_at": "2024-03-12T20:08:30.663+00:00",
767
        "published_at": "2024-03-12T20:08:30.715+00:00",
768
        "publication_scheduled_at": null,
769
        "unpublishing_scheduled_at": null,
770
        "first_published_at": "2024-03-12T20:08:30.715+00:00",
771
        "is_valid": true,
772
        "is_current_version_valid": true,
773
        "is_published_version_valid": true,
774
        "status": "published",
775
        "current_version": "FcT-R4rdRJW9Q4VB16lcpA",
776
        "stage": null
777
      }
778
    },
779
    {
780
      "id": "SgdmhG1hRGm_nCUfzUOVyA",
781
      "type": "item",
782
      "attributes": {
783
        "name": "We Built This City"
784
      },
785
      "relationships": {
786
        "item_type": {
787
          "data": {
788
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
789
            "type": "item_type"
790
          }
791
        },
792
        "creator": {
793
          "data": {
794
            "id": "254268",
795
            "type": "access_token"
796
          }
797
        }
798
      },
799
      "meta": {
800
        "created_at": "2024-03-12T20:08:30.636+00:00",
801
        "updated_at": "2024-03-12T20:08:30.663+00:00",
802
        "published_at": "2024-03-12T20:08:30.898+00:00",
803
        "publication_scheduled_at": null,
804
        "unpublishing_scheduled_at": null,
805
        "first_published_at": "2024-03-12T20:08:30.898+00:00",
806
        "is_valid": true,
807
        "is_current_version_valid": true,
808
        "is_published_version_valid": true,
809
        "status": "published",
810
        "current_version": "LLxY-PY0RhaFxMb91SvRfQ",
811
        "stage": null
812
      }
813
    },
814
    {
815
      "id": "QNVucI-QTXOW28BI_BODEw",
816
      "type": "item",
817
      "attributes": {
818
        "name": "Someday"
819
      },
820
      "relationships": {
821
        "item_type": {
822
          "data": {
823
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
824
            "type": "item_type"
825
          }
826
        },
827
        "creator": {
828
          "data": {
829
            "id": "254268",
830
            "type": "access_token"
831
          }
832
        }
833
      },
834
      "meta": {
835
        "created_at": "2024-03-12T20:08:30.617+00:00",
836
        "updated_at": "2024-03-12T20:08:30.645+00:00",
837
        "published_at": "2024-03-12T20:08:30.726+00:00",
838
        "publication_scheduled_at": null,
839
        "unpublishing_scheduled_at": null,
840
        "first_published_at": "2024-03-12T20:08:30.726+00:00",
841
        "is_valid": true,
842
        "is_current_version_valid": true,
843
        "is_published_version_valid": true,
844
        "status": "published",
845
        "current_version": "ddNw2_qDQWu34BrBt8vgZg",
846
        "stage": null
847
      }
848
    },
849
    {
850
      "id": "L5cEb4ABQ86F09KMnvmZHA",
851
      "type": "item",
852
      "attributes": {
853
        "name": "Vision of Love"
854
      },
855
      "relationships": {
856
        "item_type": {
857
          "data": {
858
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
859
            "type": "item_type"
860
          }
861
        },
862
        "creator": {
863
          "data": {
864
            "id": "254268",
865
            "type": "access_token"
866
          }
867
        }
868
      },
869
      "meta": {
870
        "created_at": "2024-03-12T20:08:30.625+00:00",
871
        "updated_at": "2024-03-12T20:08:30.643+00:00",
872
        "published_at": "2024-03-12T20:08:30.726+00:00",
873
        "publication_scheduled_at": null,
874
        "unpublishing_scheduled_at": null,
875
        "first_published_at": "2024-03-12T20:08:30.726+00:00",
876
        "is_valid": true,
877
        "is_current_version_valid": true,
878
        "is_published_version_valid": true,
879
        "status": "published",
880
        "current_version": "O1AIxobDR_SY1iDgLIKrXg",
881
        "stage": null
882
      }
883
    },
884
    {
885
      "id": "SDt2EmrzQr-KKS0lQKfQug",
886
      "type": "item",
887
      "attributes": {
888
        "name": "We Found Love"
889
      },
890
      "relationships": {
891
        "item_type": {
892
          "data": {
893
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
894
            "type": "item_type"
895
          }
896
        },
897
        "creator": {
898
          "data": {
899
            "id": "254268",
900
            "type": "access_token"
901
          }
902
        }
903
      },
904
      "meta": {
905
        "created_at": "2024-03-12T20:08:30.611+00:00",
906
        "updated_at": "2024-03-12T20:08:30.625+00:00",
907
        "published_at": "2024-03-12T20:08:30.723+00:00",
908
        "publication_scheduled_at": null,
909
        "unpublishing_scheduled_at": null,
910
        "first_published_at": "2024-03-12T20:08:30.723+00:00",
911
        "is_valid": true,
912
        "is_current_version_valid": true,
913
        "is_published_version_valid": true,
914
        "status": "published",
915
        "current_version": "HtywHW7aSXiqY8yOrn8MNQ",
916
        "stage": null
917
      }
918
    },
919
    {
920
      "id": "JHCg3GESTBCp9D6UHz9UyQ",
921
      "type": "item",
922
      "attributes": {
923
        "name": "I'll Walk Alone"
924
      },
925
      "relationships": {
926
        "item_type": {
927
          "data": {
928
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
929
            "type": "item_type"
930
          }
931
        },
932
        "creator": {
933
          "data": {
934
            "id": "254268",
935
            "type": "access_token"
936
          }
937
        }
938
      },
939
      "meta": {
940
        "created_at": "2024-03-12T20:08:30.601+00:00",
941
        "updated_at": "2024-03-12T20:08:30.616+00:00",
942
        "published_at": "2024-03-12T20:08:30.698+00:00",
943
        "publication_scheduled_at": null,
944
        "unpublishing_scheduled_at": null,
945
        "first_published_at": "2024-03-12T20:08:30.698+00:00",
946
        "is_valid": true,
947
        "is_current_version_valid": true,
948
        "is_published_version_valid": true,
949
        "status": "published",
950
        "current_version": "GRt_lHV6Slqnja3nyCFwlA",
951
        "stage": null
952
      }
953
    },
954
    {
955
      "id": "LRltshTASSyT5S-XcLp3AQ",
956
      "type": "item",
957
      "attributes": {
958
        "name": "Like a Prayer"
959
      },
960
      "relationships": {
961
        "item_type": {
962
          "data": {
963
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
964
            "type": "item_type"
965
          }
966
        },
967
        "creator": {
968
          "data": {
969
            "id": "254268",
970
            "type": "access_token"
971
          }
972
        }
973
      },
974
      "meta": {
975
        "created_at": "2024-03-12T20:08:30.576+00:00",
976
        "updated_at": "2024-03-12T20:08:30.582+00:00",
977
        "published_at": "2024-03-12T20:08:30.607+00:00",
978
        "publication_scheduled_at": null,
979
        "unpublishing_scheduled_at": null,
980
        "first_published_at": "2024-03-12T20:08:30.607+00:00",
981
        "is_valid": true,
982
        "is_current_version_valid": true,
983
        "is_published_version_valid": true,
984
        "status": "published",
985
        "current_version": "aHKqe8epQX60p_T2UdeCGQ",
986
        "stage": null
987
      }
988
    },
989
    {
990
      "id": "JujCZAUxSZKMgq2GoU6-0A",
991
      "type": "item",
992
      "attributes": {
993
        "name": "Unbelievable"
994
      },
995
      "relationships": {
996
        "item_type": {
997
          "data": {
998
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
999
            "type": "item_type"
1000
          }
1001
        },
1002
        "creator": {
1003
          "data": {
1004
            "id": "254268",
1005
            "type": "access_token"
1006
          }
1007
        }
1008
      },
1009
      "meta": {
1010
        "created_at": "2024-03-12T20:08:30.564+00:00",
1011
        "updated_at": "2024-03-12T20:08:30.572+00:00",
1012
        "published_at": "2024-03-12T20:08:30.600+00:00",
1013
        "publication_scheduled_at": null,
1014
        "unpublishing_scheduled_at": null,
1015
        "first_published_at": "2024-03-12T20:08:30.600+00:00",
1016
        "is_valid": true,
1017
        "is_current_version_valid": true,
1018
        "is_published_version_valid": true,
1019
        "status": "published",
1020
        "current_version": "ZHKL6ZzdTCeKe-fjakChiA",
1021
        "stage": null
1022
      }
1023
    },
1024
    {
1025
      "id": "PFrB-unuQ2CV48tqaxHRCg",
1026
      "type": "item",
1027
      "attributes": {
1028
        "name": "Too Close"
1029
      },
1030
      "relationships": {
1031
        "item_type": {
1032
          "data": {
1033
            "id": "ZHiqi1KiTAuLf8GFN4k1Hg",
1034
            "type": "item_type"
1035
          }
1036
        },
1037
        "creator": {
1038
          "data": {
1039
            "id": "254268",
1040
            "type": "access_token"
1041
          }
1042
        }
1043
      },
1044
      "meta": {
1045
        "created_at": "2024-03-12T20:08:30.564+00:00",
1046
        "updated_at": "2024-03-12T20:08:30.571+00:00",
1047
        "published_at": "2024-03-12T20:08:30.595+00:00",
1048
        "publication_scheduled_at": null,
1049
        "unpublishing_scheduled_at": null,
1050
        "first_published_at": "2024-03-12T20:08:30.595+00:00",
1051
        "is_valid": true,
1052
        "is_current_version_valid": true,
1053
        "is_published_version_valid": true,
1054
        "status": "published",
1055
        "current_version": "IxNPJWfuQGCk35HsB5PRqw",
1056
        "stage": null
1057
      }
1058
    }
1059
  ],
1060
  "meta": {
1061
    "total_count": 264
1062
  }
1063
}

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.

You can narrow your search to some models by specifying the field[type] attribute. 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 it use the environment's default locale.

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
}

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

By default, we would return those nested blocks as references, like:

1
[
2
  {
3
    "item": "ahxSnFQEQ02K3TjttWAg-Q", "type": "block"
4
  },
5
  {
6
    "item": "AppHB06oRBm-er3oooL_LA", "type": "block"
7
  }
8
]

But if you add the nested=true query parameter, we'll embed the block content inline for you.

When nested=true, the maximum records you can request at once is limited to 30, compared to the usual 500.

1
GET https://site-api.datocms.com/items?filter[ids]=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?filter[ids]=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?filter[ids]=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
{
8
  "data": [
9
    {
10
      "id": "FEzWmQhjQgeHsCrUtvlEMw",
11
      "type": "item",
12
      "attributes": {
13
        "structured_text_field": {
14
          "schema": "dast",
15
          "document": {
16
            "children": [
17
              {
18
                "item": {
19
                  "type": "item",
20
                  "attributes": {
21
                    "button_label": "Example button",
22
                    "button_url": "https://www.example.com"
23
                  },
24
                  "relationships": {
25
                    "item_type": {
26
                      "data": {
27
                        "id": "SkVjHJSGR5CyK16E8TfJxg",
28
                        "type": "item_type"
29
                      }
30
                    }
31
                  },
32
                  "id": "ahxSnFQEQ02K3TjttWAg-Q"
33
                },
34
                "type": "block"
35
              },
36
              {
37
                "item": {
38
                  "type": "item",
39
                  "attributes": {
40
                    "nested_structured_text_field": {
41
                      "schema": "dast",
42
                      "document": {
43
                        "children": [
44
                          {
45
                            "children": [
46
                              {
47
                                "type": "span",
48
                                "value": "This is a "
49
                              },
50
                              {
51
                                "marks": ["emphasis"],
52
                                "type": "span",
53
                                "value": "nested"
54
                              },
55
                              {
56
                                "type": "span",
57
                                "value": " structured text block inside the parent structured text field."
58
                              }
59
                            ],
60
                            "type": "paragraph"
61
                          },
62
                          {
63
                            "item": {
64
                              "type": "item",
65
                              "attributes": {
66
                                "button_label": "And this is a button inside the nested structured text block",
67
                                "button_url": "https://www.example2.com"
68
                              },
69
                              "relationships": {
70
                                "item_type": {
71
                                  "data": {
72
                                    "id": "SkVjHJSGR5CyK16E8TfJxg",
73
                                    "type": "item_type"
74
                                  }
75
                                }
76
                              },
77
                              "id": "CGqwjPDsTHKGFy1IbC0RAQ"
78
                            },
79
                            "type": "block"
80
                          }
81
                        ],
82
                        "type": "root"
83
                      }
84
                    }
85
                  },
86
                  "relationships": {
87
                    "item_type": {
88
                      "data": {
89
                        "id": "Ty4S40cbQH6_VMNnGdd9KA",
90
                        "type": "item_type"
91
                      }
92
                    }
93
                  },
94
                  "id": "AppHB06oRBm-er3oooL_LA"
95
                },
96
                "type": "block"
97
              }
98
            ],
99
            "type": "root"
100
          }
101
        }
102
      },
103
      "relationships": {
104
        "item_type": {
105
          "data": {
106
            "id": "UVa_hHEBSeefLEUnwoQFig",
107
            "type": "item_type"
108
          }
109
        },
110
        "creator": {
111
          "data": {
112
            "id": "104280",
113
            "type": "account"
114
          }
115
        }
116
      },
117
      "meta": {
118
        "created_at": "2024-03-13T17:01:19.243+00:00",
119
        "updated_at": "2024-03-13T17:14:17.444+00:00",
120
        "published_at": "2024-03-13T17:14:17.597+00:00",
121
        "publication_scheduled_at": null,
122
        "unpublishing_scheduled_at": null,
123
        "first_published_at": "2024-03-13T17:01:19.326+00:00",
124
        "is_valid": true,
125
        "is_current_version_valid": true,
126
        "is_published_version_valid": true,
127
        "status": "published",
128
        "current_version": "DLtyHZ2MTDqYMg7g5mgYEw",
129
        "stage": null
130
      }
131
    }
132
  ],
133
  "meta": {
134
    "total_count": 1
135
  }
136
}

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.