List all records - Record - Content Management API

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 Optional

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

filter object Optional

Attributes to filter records

locale string Optional

When filter[query] or field[fields] is defined, filter by this locale. Default: environment's main locale

page object Optional

Attributes to manage results pagination

order_by string Optional

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.

version string Optional

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

Returns

Returns an array of item resource objects.

Examples

The following examples are available:

Fetching one page of results vs. the whole collection
Fetching records by their IDs
Fetching records belonging to a model
Fetching a filtered list of records by model fields
Fetching records by a textual generic query

Fetching one page of results vs. the whole collection

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:

Example code:

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();

Fetching records by their IDs

You can retrieve a list of records (or block records) by their IDs.

Example code:

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();

Fetching records belonging to a model

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:

Example code:

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();

Fetching a filtered list of records by model fields

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.

You can add an optional locale parameter if you are filtering by a localized field.
You can add an optional order_by parameter.

In this example we are filtering by a single line string field and by a date field:

Example code:

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();

Fetching records by a textual generic query

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.

Example code:

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 only
      type: 'article,blog_post',
      query: 'egyptian museum',
    },
    locale: 'en',
    // possible values: `_rank_DESC` (default) | `_rank_ASC`
    order_by: '_rank_DESC',
  });
  console.log(records);
}
run();

Questions?

We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.