API Docs

Get Records

Retrieves details of multiple records from an App by specifying the App ID and a query string.

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/records.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/records.json
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json (not needed if specifying the query with a query string)

Contents

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
fields Array of Strings Optional The field codes to be included in the response.
Ignoring this parameter will return all accessible fields that exist in the App.
app Integer or String Yes The App ID.
query String Optional The query string that specifies what records to include in the response.
Refer to the following document for more information:
Query Strings
Ignoring this parameter will return all accessible records from the App.
totalCount Boolean or String Optional If set to true, the total count of records that match the query conditions will be included in the response.
If ignored, null is returned for the totalCount value.

Sample Requests (Query string)

A sample request for using the Get Records API that specifies:

  • An App ID of 8
  • A query of _Created_by in (LOGINUSER()) and Created_datetime = TODAY() order by $id asc limit 100 offset 0_
  • The following fields to be included in the response
    • The Record ID field
    • The Created By field (with field line of "Created_by")
    • The Created Datetime field (with field line of "Created_datetime")

The query string is sent by joining the "app", "query" and "fields" parameters with an "&", and URL encoding each parameter name of the query and their corresponding values.

Query String 

1

app=8&query=Created_by%20in%20(LOGINUSER())%20and%20Created_datetime%20%3D%20TODAY()%20order%20by%20%24id%20asc%20limit%20100%20offset%200&fields[0]=%24id&fields[1]=Created_by&fields[2]=Created_datetime

JavaScript using kintone.api() 

1
2
3
4
5
6
7
8
9

var query = 'Created_by in (LOGINUSER()) and Created_datetime = TODAY() order by $id asc limit 100 offset 0';
var fields = '&fields[0]=$id&fields[1]=Created_by&fields[2]=Created_datetime';
kintone.api(kintone.api.url('/k/v1/records.json', true) + '?app=8&query=' + query + fields, 'GET', {}, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample 

1
2
3

curl -X GET 'https://{subdomain}.kintone.com/k/v1/records.json?app=8&query=Created_by%20in%20(LOGINUSER())%20and%20Created_datetime%20%3D%20TODAY()' \
'%20order%20by%20%24id%20asc%20limit%20100%20offset%200&fields[0]=%24id&fields[1]=Created_by&fields[2]=Created_datetime' \
 -H 'X-Cybozu-API-Token: {APIToken}'

Sample Requests (JSON)

JavaScript using kintone.api() with JSON 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var body = {
  'app': 8,
  'query': 'Created_by in (LOGINUSER()) and Created_datetime = TODAY() order by $id asc limit 100 offset 0',
  'fields': ['$id', 'Created_by', 'Created_datetime']
};

kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample 

1
2
3
4

curl -X GET 'https://{subdomain}.kintone.com/k/v1/records.json' \
 -H 'X-Cybozu-API-Token: {APIToken}' \
 -H 'Content-Type: application/json' \
 -d '{"app": 8, "query": "Created_by in (LOGINUSER()) and Created_datetime = TODAY() order by $id asc limit 100 offset 0", "fields": ["$id", "Created_by", "Created_datetime"]}'

Response Parameters

Parameter Type Description
records Array An array of objects, including field types and field values within the matching records.
totalCount String The total count of records that match the query conditions.
If the totalCount parameter is ignored or is set as false in the request, null is returned.

Sample Response

An object of an array of records with field data are responded from the specified App.

Each record in the array includes the field type and value(s) stored in the record.

For field type specs, refer to the following document:
Field Types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

{
  "records": [
    {
      "Created_datetime": {
        "type": "CREATED_TIME",
        "value": "2019-03-11T04:50:00Z"
      },
      "Created_by": {
        "type": "CREATOR",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "$id": {
        "type": "__ID__",
        "value": "1"
      }
    },
    {
      "Created_datetime": {
        "type": "CREATED_TIME",
        "value": "2019-03-11T06:42:00Z"
      },
      "Created_by": {
        "type": "CREATOR",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "$id": {
        "type": "__ID__",
        "value": "2"
      }
    }
  ],
  "totalCount": null
}

Query Operators and Functions

For more information on Query Strings, refer to the following document:
Query string

Limitations

  • The maximum number of records that can be retrieved with the Get Records API is 500.
  • The scope of the array index you can specify for field queries is between 0 and 99.
  • Up to 1000 fields can be specified in the request body.
  • The maximum offset value that can be specified is 10000.
  • The filtering will be aborted if there are more than 100,000 matches for the query.
    In this case, "x-cybozu-warning : Filter aborted because of too many search results." will be returned in the response header.
  • For other limitations, refer to the limitations section in the following article:
    Kintone REST API Overview

Notes

  • The language of the returned record data depends on the method of authentication used:
    • When the Accept-Language request header is specified, the specified language will be returned, if it has been set in the locale settings. For more information about request headers, refer to the following document:
      Request headers
    • API Token authentication: The Administrator account's display language will be used.
    • Other forms of authentication: The user account's display language will be used.
    • When the display language is set to Use Web browser settings, the language specified in the Users and Systems Administration locale setting will be used.
    • The system locale can be changed via the Users and Systems Administration Locale Settings. For more information, refer to the following article:
      Configuring System Language (External link)