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 Optional boolean Example: true

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

filter Optional object

Attributes to filter records

locale Optional string Example: "it"

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

page Optional object

Parameters to control offset-based pagination

order_by Optional string Example: "name_DESC"

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 Optional string Example: "current"

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

Example Basic example: Fetching records

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

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const results = await client.items.list();
  console.log(results); // By default, we return the first 30 records
}
run();

Example Fetching a specific page of records

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: limit: 2 and offset: 3 (because record counting starts from 0)

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const twoRecords = await client.items.list({
    page: {
      limit: 2,
      offset: 3,
    },
  });
  console.log(twoRecords);
}
run();

Example Fetching all pages

Instead of fetching a single page at a time, sometimes you want to get all the pages together.

You can do this using the client.items.listPagedIterator() method with an async iteration statement, which will handle pagination for you. All the details on how to use listPagedIterator() are outlined on this page.

Note that this will return records across all your models, unless you specify a filter. Unfiltered, this is useful for fetching all the records in your project (e.g. for backup or export purposes). To filter by IDs or models, see the other examples below.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  // We'll be building up an array of all records using an AsyncIterator, `client.items.listPagedIterator()`
  const allRecords = [];
  for await (const record of client.items.listPagedIterator()) {
    allRecords.push(record);
  }
  console.log(allRecords);
}
run();

Example Fetching records by their IDs

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

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const records = await client.items.list({
    filter: {
      // Specific record IDs: one dog record, and one song record
      // Note that it's a comma-separated string with no spaces
      ids: "QHr0FFO0Ro6DtNBrFCwV0A,cSp-WX-_R7m_r_hG0D0Ekg",
    },
  });
  console.log(records);
}
run();

Example Fetching records belonging to a model

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:

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const records = await client.items.list({
    filter: {
      // Filtering by the model with api_key "cat" and the model with ID of "dog"
      type: "cat,MtzQYUvbS-S0LM2LZ5QlkQ",
    },
  });
  console.log(records);
}
run();

Example Fetching draft or updated records and filtering by publication status

By default, the API only returns published records. Using the version parameter, you can choose to also include drafts and updates.

version: 'current' will return the most recent versions of the queried records. Sometimes this can be the same as the published version, but other times it could be an unpublished draft or update:

draft means the record has been created and saved, but not yet published (or was unpublished)
published means the record has been published, and there are no later changes (i.e., the published version is the most recent version)
updated means the record was previously published, but there are new changes that have been saved and not yet published (the current version is ahead of the published version)

To get only draft, updated, or published records, you can filter on this response's record.meta.status property on the client side, after the fetch:

import { buildClient } from "@datocms/cma-client";
const getPublishedAndDraftRecordsOfModel = async () => {
  const client = buildClient({
    apiToken: process.env.DATOCMS_READONLY_TOKEN,
  });
  const allRecords = await client.items.list({
    filter: {
      type: "post", // Model name or internal ID
    },
    version: "current", // Fetch the latest version of the records, regardless of publication status
  });
  // Records that have been saved but not published (or were unpublished later)
  const newDraftsOnly = allRecords.filter(
    (record) => record.meta.status === "draft",
  );
  // Records that were published but have unsaved changes ahead of the published version
  const updatedRecordsOnly = allRecords.filter(
    (record) => record.meta.status === "updated",
  );
  // Records that were published and have no further changes
  const publishedRecordsOnly = allRecords.filter(
    (record) => record.meta.status === "published",
  );
  console.log(`There are ${allRecords.length} total records in this model.`);
  console.log(`${publishedRecordsOnly.length} are published.`);
  console.log(`${updatedRecordsOnly.length} have unpublished updates.`);
  console.log(`${newDraftsOnly.length} are unpublished drafts.`);
};
getPublishedAndDraftRecordsOfModel();

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

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)

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const records = await client.items.list({
    filter: {
      type: "dog",
      fields: {
        name: {
          in: ["Buddy", "Rex"],
        },
        breed: {
          eq: "mixed",
        },
      },
      _updated_at: {
        gt: "2020-04-18T00:00:00",
      },
    },
    order_by: "_updated_at_ASC",
  });
  console.log(records);
}
run();

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

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const records = await client.items.list({
    filter: {
      // optional, if defined, search in the specified models only
      type: "dog,cat",
      query: "chicken",
    },
    locale: "en",
    order_by: "_rank_DESC", // possible values: `_rank_DESC` (default) | `_rank_ASC`
  });
  console.log(records);
}
run();

Example Fetching nested blocks inside a record

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:

[
  { item: 'ahxSnFQEQ02K3TjttWAg-Q', type: 'block' },
  { item: 'AppHB06oRBm-er3oooL_LA', type: 'block' }
]

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.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
  const records = await client.items.list({
    filter: {
      ids: "FEzWmQhjQgeHsCrUtvlEMw", // Only one record, an example post
    },
    nested: true, // But retrieve its nested block content as well
  });
  // Instead of console.log, console.dir will fully expand nested objects
  // See https://nodejs.org/api/console.html#consoledirobj-options
  // This way, we can better see the embedded blocks in the response
  console.dir(records, { depth: null });
}
run();

Did this doc help you?

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