Retrieve Multiple Records

kintone offers a rich set of APIs that allow you to directly manipulate application data from your programs.

In particular, the REST API is a powerful tool for manipulating kintone data through HTTP requests.

This page provides a detailed explanation on how to retrieve multiple specific records using the kintone REST API.

If you want to retrieve only one record, the endpoint is different. Please refer to the following page for details.

Using from kintone

When executing the REST API as a JavaScript customization in kintone, you can easily execute the REST API by using the provided JavaScript API.

By using the kintone.api.url method of the JavaScript API, you can obtain the REST API endpoint without being aware of the execution space.

/**
 * Retrieve records that match the specified conditions using the kintone REST API
 *
 * @param { Object } params
 * @param { string | number } params.app - App ID
 * @param { string[] } params.fields - Field codes of the fields to retrieve
 * @param { string } params.query - Conditions to retrieve records
 * @param { boolean } params.totalCount - Whether to retrieve the total count of the records
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - Record information
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', {
    app,
    fields,
    query,
    totalCount,
  });
};

Note that when retrieving only one record, specify record.json, but when retrieving multiple records, specify records.json.

Specify the App ID and the record ID of the records you want to retrieve as arguments.

If the target record exists, an object with the record property will be returned.

(() => {
  const getRecords = (params) => {
    /** Omitted */
  };

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const appId = kintone.app.getId();
    const query = `Start_Date > "2024-01-01" and Contract_Status in ("Active", "Expired")`; // Conditions to retrieve records
    const { records } = await getRecords({ app: appId, query });
    console.log(records); // [{ Field_Code: Value, ... }, ...]
    return event;
  });
})();

(() => {
  const getRecords = (params) => {
    /** Omitted */
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    const query = prompt('Please enter the conditions to retrieve the records');
    const appId = kintone.app.getId();
    const { records } = await getRecords({ app: appId, query });
    console.log(records); // [{ Field_Code: Value, ... }, ...]
    return event;
  });
})();

Using from outside kintone

The kintone REST API can be used from various environments such as Excel, GAS, Node.js, etc.

By using the REST API, you can operate applications using kintone data from environments other than kintone.

Using Node.js

When using the kintone REST API from Node.js, you can send HTTP requests with almost the same code as executing JavaScript in the browser.

/**
 * Retrieve records that match the specified conditions using the kintone REST API
 * @param { Object } params
 * @param { string | number } params.app - App ID
 * @param { string[] } params.fields - Field codes of the fields to retrieve
 * @param { string } params.query - Conditions to retrieve records
 * @param { boolean } params.totalCount - Whether to retrieve the total count of the records
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - Record information
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  const queryParams = new URLSearchParams({ app, fields, query, totalCount }).toString();
  return fetch(`https://__your_subdomain__.cybozu.com/k/v1/records.json?${queryParams}`, {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  }).then((res) => res.json());
};

Replace __your_subdomain__ and YOUR_API_TOKEN with your own environment.

You can set them as arguments, but it is also fine to set them directly within the function.

Unlike the code used from kintone mentioned earlier, if the referenced app is in a guest space, you need to change the URL.

Using GAS

When using the kintone REST API from Google Apps Script (GAS), you can send HTTP requests using the UrlFetchApp class.

/**
 * Retrieve records that match the specified conditions using the kintone REST API
 * @param { Object } params
 * @param { string | number } params.app - App ID
 * @param { string[] } params.fields - Field codes of the fields to retrieve
 * @param { string } params.query - Conditions to retrieve records
 * @param { boolean } params.totalCount - Whether to retrieve the total count of the records
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - Record information
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  const queryParams = yourCustomQueryParamsFunction({ app, fields, query, totalCount });
  const url = `https://__your_subdomain__.cybozu.com/k/v1/records.json?${queryParams}`;
  const options = {
    method: 'GET',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
  };
  const response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};

In GAS, use the UrlFetchApp class to send HTTP requests.

Also, since the URLSearchParams class is not available, you need to prepare a function to create query parameters separately.

Using Python

When using the kintone REST API from Python, you can send HTTP requests using the requests library.

import requests

def get_records(params):
    app = params['app']
    fields = params['fields']
    query = params['query']
    totalCount = params['totalCount']
    url = f'https://__your_subdomain__.cybozu.com/k/v1/records.json'
    headers = {
        'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    }
    params = {
        'app': app,
        'fields': fields,
        'query': query,
        'totalCount': totalCount,
    }
    response = requests.get(url, headers=headers, params=params)
    return response.json()

Using the Command Line

When using the kintone REST API from the command line, you can send HTTP requests using the curl command.

curl -X GET 'https://__your_subdomain__.cybozu.com/k/v1/records.json?app=1&query=Record_Number > 10' \
  -H 'X-Cybozu-API-Token: YOUR_API_TOKEN'

Limitations

When retrieving multiple records in kintone, there are the following limitations:

• The maximum number of records that can be retrieved in one request is 500
• The upper limit of the offset value for the query parameter is 10,000

For methods to retrieve records without being aware of these limitations, please refer to the following page.