List all records - Record - Content Management API

In case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the public REST API and you are able to replicate the same calls.

Take a look at the examples below with the most common search scenarios.

Query parameters

nested string 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

orderBy 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>_<DIRECTION(ASC|DESC)>. 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 objects.

Examples

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
Another example and fetching all pages

Fetching records by their IDs

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

Add allPages to automatically paginate the request and get all the records.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function getFilteredRecords() {
  const records = await client.items.all(
    {
      filter: {
        ids: "123,567",
      },
    },
    {
      allPages: true,
    }
  );
  console.log(records);
}
getFilteredRecords();

Returned output:

[
  {
    id: '123',
    title: 'article title',
    updatedAt: '2021-07-14T15:46:32.276+02:00',
    createdAt: '2021-07-14T15:33:03.065+02:00',
    meta: { ... },
    itemType: '966629',
    creator: { id: '777', type: 'account' }
  },
  {
    id: '567',
    content: 'article content\n',
    updatedAt: '2021-07-14T15:46:32.252+02:00',
    createdAt: '2021-07-14T15:46:32.249+02:00',
    meta: { ... },
    itemType: '966835',
    creator: { id: '777', type: 'account' }
  }
]

Fetching records belonging to a model

You can retrieve a paginated list of records belonging to one (or many) models. You can use either model's api_key or model's ID. Multiple comma separated values are accepted.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function getFilteredRecords() {
  const records = await client.items.all({
    filter: {
      type: "dog,cat", // you can use models `api_key`s or models IDs
    },
  });
  console.log(records);
}
getFilteredRecords();

Returned output:

[
  {
    id: '123',
    name: 'Gigio',
    updatedAt: '2021-07-14T15:46:32.276+02:00',
    createdAt: '2021-07-14T15:33:03.065+02:00',
    meta: { ... },
    itemType: '1234', // `dog` model
    creator: { id: '777', type: 'account' }
  },
  {
    id: '567',
    name: 'Felix',
    updatedAt: '2021-07-14T15:46:32.252+02:00',
    createdAt: '2021-07-14T15:46:32.249+02:00',
    meta: { ... },
    itemType: '5678', // `cat` model
    creator: { id: '777', type: 'account' }
  },
  ...
]

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.

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

The filtering options are the same as the GraphQL API records filters. So please check there all the options.

The only difference is that when using this API you should snake_case the fields instead of camelCasing as in the GraphQL API.

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

You can add an optional order_by attribute.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function getFilteredRecords() {
  const records = await client.items.all({
    filter: {
      type: "dog",
      fields: {
        name: {
          eq: "Gigio",
        },
        _updated_at: {
          gt: "2020-04-18T00:00:00",
        },
      },
    },
  });
  console.log(records);
}
getFilteredRecords();

Returned output:

[
  {
    id: "4579273",
    name: "Gigio",
    picture: {
      uploadId: "1642386",
      alt: null,
      title: null,
      focalPoint: { x: 0.5, y: 0.5 },
      customData: {},
    },
    description: [],
    breed: "Labrador",
    age: 4,
    height: 50.5,
    dateOfBirth: "2020-04-17T17:25:00+01:00",
    available: true,
    location: { latitude: 45.0703393, longitude: 7.686864 },
    color: { red: 239, blue: 156, alpha: 255, green: 208 },
    json: '{"additionalData": "1234"}',
    friends: ["4572300", "4572298", "4572297", "4572180", "4572128"],
    updatedAt: "2020-04-20T11:06:29.130+01:00",
    createdAt: "2020-04-20T11:06:29.126+01:00",
    meta: { ... },
    itemType: "1234",
    creator: { id: "322", type: "access_token" },
  },
];

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

You can narrow your search on some models by specifying the field[type] attribute. You can use either model's api_key or model's ID. Multiple comma separated values are accepted.

You should specify the locale attribute. It will be used the environment's main locale as default.

Returned records are ordered by rank.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function getFilteredRecords() {
  const records = await client.items.all({
    filter: {
      type: "article,blog_post", // optional, if defined, search in the specified models only
      query: "egyptian museum",
    },
    locale: "en",
    order_by: "_rank_DESC", // possible values: `_rank_DESC` (default) | `_rank_ASC`
  });
  console.log(records);
}
getFilteredRecords();

Returned output:

[
  {
    id: '59707172',
    title: { en: 'Egyptian Museum of Torino' },
    content: { en: 'A must see museum!' },
    updatedAt: '2021-10-18T11:39:18.282+02:00',
    createdAt: '2021-10-18T11:30:46.765+02:00',
    position: 1,
    parentId: null,
    meta: { ... },
    itemType: '210943',
    creator: { id: '14379', type: 'account' }
  },
  {
    id: '59707173',
    title: { en: '10 things to do in Torino' },
    content: { en: '- Visit the egyptian museum\n- ...' },
    updatedAt: '2021-10-18T11:39:38.123+02:00',
    createdAt: '2021-10-18T11:32:07.576+02:00',
    meta: { ... },
    itemType: '1195677',
    creator: { id: '14379', type: 'account' }
  }
]

Another example and fetching all pages

Example code:

const SiteClient = require('datocms-client').SiteClient;
const client = new SiteClient('YOUR-API-TOKEN');
client.items.all({
  nested: 'true',
  filter: {
    ids: '12,31',
    type: '44',
    query: 'foo',
    fields: {
      name: {
        eq: 'Gigio'
      }
    }
  },
  locale: 'it',
  page: {
    offset: 200,
    limit: 100
  },
  order_by: 'name_DESC',
  version: 'current'
})
.then((items) => {
    items.forEach((item) => {
      console.log(item);
    });
  })
.catch((error) => {
  console.error(error);
});
// if you want to fetch all the pages with just one call:
client.items.all({
  nested: 'true',
  filter: {
    ids: '12,31',
    type: '44',
    query: 'foo',
    fields: {
      name: {
        eq: 'Gigio'
      }
    }
  },
  locale: 'it',
  order_by: 'name_DESC',
  version: 'current'
}, {
  allPages: true
})
.then((items) => {
    items.forEach((item) => {
      console.log(item);
    });
  })

Returned output:

> node example.js
{
  "id": "4235",
  "title": "My first blog post!",
  "content": "Lorem ipsum dolor sit amet...",
  "category": "24",
  "image": {
    "alt": "Alt text",
    "title": "Image title",
    "customData": {},
    "focalPoint": null,
    "uploadId": "20042921"
  },
  "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
    "status": "draft",
    "is_valid": true,
    "current_version": "4234",
    "stage": ""
  },
  "itemType": "44",
  "creator": "312"
}

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.