Show examples in:
    List all records

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

    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>_<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 resource objects.

    Examples

    The following examples are available:

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