Sorry, no results found for "".
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, Structured Text and Single Block fields. If set, returns full payload for nested blocks instead of IDs
Attributes to filter records
Record (or block record) IDs to fetch, comma separated. If you use this filter, you must not use filter[type] or filter[fields]
"c89tCUarTvGKxA37acCEWA,aCiWeOsUT3mxY0KIzUfAhw"
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
"cat,dog"
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.
"foo"
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.
{ name: { eq: "Buddy" } }
When set, only valid records are included in the results.
"true"
When filter[query] or field[fields] is defined, filter by this locale. Default: environment's main locale
"it"
Parameters to control offset-based pagination
The (zero-based) offset of the first entity returned in the collection (defaults to 0)
200
The maximum number of entities to return (defaults to 30, maximum is 500)
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.
"name_DESC"
Whether you want the currently published versions (published, default) of your records, or the latest available (current)
"current"
Returns an array of resource objects of type item
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();Showing the default number of results (30 records) from any model
[ { id: "VDd0Ig2WTZukQ8DU9ZskXg", type: "item", name: "Shout", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.887+00:00", updated_at: "2024-03-12T20:08:33.895+00:00", published_at: "2024-03-12T20:08:33.945+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.945+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "LPlwzflrSYyH4FQhCubRgQ", stage: null, }, }, { id: "fPW3GwaCTAaCfHWr9C1RrQ", type: "item", name: "Coming Up", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.841+00:00", updated_at: "2024-03-12T20:08:33.850+00:00", published_at: "2024-03-12T20:08:33.882+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.882+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "IiCnty-tSdGnvBUZPd_g4A", stage: null, }, }, // ...30 records in total]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();[ { id: "VDd0Ig2WTZukQ8DU9ZskXg", type: "item", name: "Shout", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.887+00:00", updated_at: "2024-03-12T20:08:33.895+00:00", published_at: "2024-03-12T20:08:33.945+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.945+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "LPlwzflrSYyH4FQhCubRgQ", stage: null, }, }, { id: "fPW3GwaCTAaCfHWr9C1RrQ", type: "item", name: "Coming Up", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.841+00:00", updated_at: "2024-03-12T20:08:33.850+00:00", published_at: "2024-03-12T20:08:33.882+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.882+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "IiCnty-tSdGnvBUZPd_g4A", stage: null, }, },]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();Showing all results of client.items.listPagedIterator(), from any model
[ { id: "VDd0Ig2WTZukQ8DU9ZskXg", type: "item", name: "Shout", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.887+00:00", updated_at: "2024-03-12T20:08:33.895+00:00", published_at: "2024-03-12T20:08:33.945+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.945+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "LPlwzflrSYyH4FQhCubRgQ", stage: null, }, }, { id: "fPW3GwaCTAaCfHWr9C1RrQ", type: "item", name: "Coming Up", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.841+00:00", updated_at: "2024-03-12T20:08:33.850+00:00", published_at: "2024-03-12T20:08:33.882+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:33.882+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "IiCnty-tSdGnvBUZPd_g4A", stage: null, }, }, // ... 164 more items]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();Showing two records from different models: dog and song. The returned record order is random, not the order of the record IDs you specified.
[ { id: "cSp-WX-_R7m_r_hG0D0Ekg", type: "item", name: "One of Us", item_type: { id: "ZHiqi1KiTAuLf8GFN4k1Hg", type: "item_type" }, creator: { id: "254268", type: "access_token" }, meta: { created_at: "2024-03-12T20:08:33.743+00:00", updated_at: "2024-03-12T20:08:33.755+00:00", published_at: "2024-03-12T20:08:34.240+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T20:08:34.240+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "SjWxQjSCRy-g_B7t1GcnPw", stage: null, }, }, { id: "QHr0FFO0Ro6DtNBrFCwV0A", type: "item", name: "Maji", breed: "mixed", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-26T20:24:36.462+00:00", updated_at: "2024-01-26T20:24:36.618+00:00", published_at: "2024-01-26T20:24:36.779+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-26T20:24:36.779+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "YmES_iXOT3GguMQXoFZcWw", stage: null, }, },]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();[ { id: "QHr0FFO0Ro6DtNBrFCwV0A", type: "item", name: "Maji", breed: "mixed", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-26T20:24:36.462+00:00", updated_at: "2024-01-26T20:24:36.618+00:00", published_at: "2024-01-26T20:24:36.779+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-26T20:24:36.779+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "YmES_iXOT3GguMQXoFZcWw", stage: null, }, }, { id: "RGLUGlQiTKiAQuB3D9C_1g", type: "item", name: "Higgins", breed: "hovawart", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-26T20:23:49.239+00:00", updated_at: "2024-01-26T20:23:49.247+00:00", published_at: "2024-01-26T20:23:49.267+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-26T20:23:49.267+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "WvWbSB9iQfG8o2mg_f5K5A", stage: null, }, },]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();There are 16 total records in this model.9 are published.3 have unpublished updates.4 are unpublished drafts.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.
locale parameter if you are filtering by a localized field.order_by parameter.In this example, we are filtering the model dog by:
name in ['Buddy','Rex'] (matching Buddy OR Rex)breed eq 'mixed' (matching exactly mixed)_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();[ { id: "EA4kSeoVQqKSR88cVq2kqQ", type: "item", name: "Rex", breed: "mixed", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-03-12T22:30:44.137+00:00", updated_at: "2024-03-12T22:30:44.146+00:00", published_at: "2024-03-12T22:30:44.178+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-12T22:30:44.178+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "QIjEZ8glRkix0gt9uz0Pfg", stage: null, }, }, { id: "B1E0yYBORgmRpa_oK5LrOw", type: "item", name: "Buddy", breed: "mixed", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-30T00:11:04.310+00:00", updated_at: "2024-03-12T22:31:26.455+00:00", published_at: "2024-03-12T22:31:26.491+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-30T00:11:04.340+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "KhshsDnyRVi3aMzBBs7QMQ", stage: null, }, },]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();[ { id: "B1E0yYBORgmRpa_oK5LrOw", type: "item", name: "Buddy", breed: "mixed", description: "Buddy loves chicken. Just make sure it's cooked and doesn't have any seasonings or bones!", item_type: { id: "MtzQYUvbS-S0LM2LZ5QlkQ", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-30T00:11:04.310+00:00", updated_at: "2024-03-12T22:31:26.455+00:00", published_at: "2024-03-12T22:31:26.491+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-30T00:11:04.340+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "KhshsDnyRVi3aMzBBs7QMQ", stage: null, }, }, { id: "c89tCUarTvGKxA37acCEWA", type: "item", name: "Sheriff", breed: "domestic_longhair", description: "Sheriff loves salmon, sweet potatoes and chicken.", item_type: { id: "JwCG35JtS_y92WZoOq1Ujw", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-01-26T20:23:31.721+00:00", updated_at: "2024-01-30T00:24:16.370+00:00", published_at: "2024-01-30T00:24:16.393+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-01-26T20:23:31.752+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "Uh_nr0kWRZy54W91MWrdLg", stage: null, }, },]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();[ { id: "FEzWmQhjQgeHsCrUtvlEMw", type: "item", structured_text_field: { schema: "dast", document: { children: [ { item: { type: "item", attributes: { button_label: "Example button", button_url: "https://www.example.com", }, relationships: { item_type: { data: { id: "SkVjHJSGR5CyK16E8TfJxg", type: "item_type" }, }, }, id: "ahxSnFQEQ02K3TjttWAg-Q", }, type: "block", }, { item: { type: "item", attributes: { nested_structured_text_field: { schema: "dast", document: { children: [ { children: [ { type: "span", value: "This is a " }, { marks: ["emphasis"], type: "span", value: "nested", }, { type: "span", value: " structured text block inside the parent structured text field.", }, ], type: "paragraph", }, { item: { type: "item", attributes: { button_label: "And this is a button inside the nested structured text block", button_url: "https://www.example2.com", }, relationships: { item_type: { data: { id: "SkVjHJSGR5CyK16E8TfJxg", type: "item_type", }, }, }, id: "CGqwjPDsTHKGFy1IbC0RAQ", }, type: "block", }, ], type: "root", }, }, }, relationships: { item_type: { data: { id: "Ty4S40cbQH6_VMNnGdd9KA", type: "item_type" }, }, }, id: "AppHB06oRBm-er3oooL_LA", }, type: "block", }, ], type: "root", }, }, item_type: { id: "UVa_hHEBSeefLEUnwoQFig", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-03-13T17:01:19.243+00:00", updated_at: "2024-03-13T17:14:17.444+00:00", published_at: "2024-03-13T17:14:17.597+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-13T17:01:19.326+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "DLtyHZ2MTDqYMg7g5mgYEw", stage: null, }, },]