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!
For Modular Content fields and Structured Text fields. If set, returns full payload for nested blocks instead of IDs
Attributes to filter records
When filter[query] or field[fields] is defined, filter by this locale. Default: environment's main locale
Attributes to manage results pagination
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.
Whether you want the currently published versions (published, default) of your records, or the latest available (current)
The following examples are available:
The client.items.list() method returns a single page of records, while if you need to iterate over every resource in the collection (and not just the first page of results), you can use the client.items.listPagedIterator() method with an async iteration statement, which automatically handles pagination for you:
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });// this only returns the first page of results:const records = await client.items.list();console.log(records);// this iterates over every page of results:for await (const record of client.items.listPagedIterator()) {console.log(record);}}run();
You can retrieve a list of records (or block records) by their IDs.
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });const records = await client.items.list({filter: {ids: '123,567',},});console.log(records);}run();
In the following example you can see how you can retrieve a page of records belonging to one (or many) models. To filter, you can use either the model's api_key or ID. Multiple comma separated values are accepted:
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });const records = await client.items.list({filter: {// you can also use models IDs instead of API keys!type: 'dog,cat',},});console.log(records);}run();
You can retrieve a paginated list of records filtered by a set of conditions on the fields. There are different options for every field and you can combine multiple filters together.
It's mandatory to define filter[type] and it must contain only one value.
The filtering options are the same as the GraphQL API records filters, so please check there all the options.
locale parameter if you are filtering by a localized field.order_by parameter.In this example we are filtering by a single line string field and by a date field:
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });const records = await client.items.list({filter: {type: 'dog',fields: {name: {eq: 'Buddy',},_updated_at: {gt: '2020-04-18T00:00:00',},},},});console.log(records);}run();
You can retrieve a list of records filtered by a textual query match. It will search in block records content too.
You can narrow your search on some models by specifying the field[type] attribute. You can use either the model's api_key or its ID. Multiple comma separated values are accepted.
You should specify the locale attribute,or it will be used the environment's main locale as default.
Returned records are ordered by rank.
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });const records = await client.items.list({filter: {// optional, if defined, search in the specified models onlytype: 'article,blog_post',query: 'egyptian museum',},locale: 'en',// possible values: `_rank_DESC` (default) | `_rank_ASC`order_by: '_rank_DESC',});console.log(records);}run();