Get Record (GET)

Get RecordGET /record.json

Retrieves details of 1 record from an app.
URI
https://{subdomain}.kintone.com/k/v1/record.json
URI for Guest Space Apps
https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/record.json

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
app Integer or String Yes The app ID.
id Integer or String Yes The Record ID.

Sample Request using Query Strings

Join "app" and "id" with an "&".

For example, let's say we're looking for a record with a record ID of "100" inside an App with am App Id of "8".

Query String

app=8&id=100

Request Header

GET /k/v1/record.json?app=8&id=100 HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=

Sample Request using JSON

Request Header

GET /k/v1/record.json HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json

Body

{
    "app": 8,
    "id": 100
}

Sample Response

A successful response will include record details inside a JSON format.

Check field types for more details.

{
    "record": {
        "attachmentfield": {
            "type": "FILE",
            "value": [
                {
                    "contentType": "image/jpeg",
                    "fileKey": "20150401060837BAC36C350D4E4AA5A736689A5875248E042",
                    "name": "animals.jpg",
                    "size": "777835"
                }
            ]
        },
        "updated_datetime": {
            "type": "UPDATED_TIME",
            "value": "2015-04-01T06:51:00Z"
        },
        "weblink": {
            "type": "LINK",
            "value": "https://www.kintone.com/"
        },
        "updatedby": {
            "type": "MODIFIER",
            "value": {
                "code": "william-sayama",
                "name": "William Sayama"
            }
        },
        "$revision": {
            "type": "__REVISION__",
            "value": "3"
        },
        "recordID": {
            "type": "RECORD_NUMBER",
            "value": "1"
        },
        "created_datetime": {
            "type": "CREATED_TIME",
            "value": "2015-03-29T06:08:00Z"
        },
        "richtext": {
            "type": "RICH_TEXT",
            "value": "<span style=\"color: rgb(0,0,255);\">test</span>"
        },
        "createdby": {
            "type": "CREATOR",
            "value": {
                "code": "billsmiles@kintone.com",
                "name": "Bill Smiles"
            }
        },
        "$id": {
            "type": "__ID__",
            "value": "1"
        }
    }
}

JavaScript Samples

kintone REST API Request Example

var body = {
    "app": 20,
    "id": 100
};
 
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});

XMLHttpRequest Example

var params = '?app=20&id=100';
var url = 'https://{subdomain}.kintone.com/k/v1/record.json' + params;
  
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();

Get RecordsGET /records.json

Retrieves details of multiple records from an app using a query string.
URI
https://{subdomain}.kintone.com/k/v1/records.json
URI for Guest Space Apps
https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/records.json

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
fields Array of Strings Optional The field codes that you want in the response. If nothing is specified, all accessible fields in the app will be returned.
app Integer or String Yes The App ID.
query String Optional The query string that will specify what records will be responded. The operators and options in the below table lists can be used in the query string. If nothing is specified, fields will be returned from all accessible records.
totalCount Boolean or String Optional If set to "true", the request will retrieve the total count of records that were retrieved that match the query conditions.
If ignored, null is returned for the totalCount value.

Operators and functions for the query parameter

Operators

OPERATOR SAMPLE DESCRIPTION
= string_0 = "test" True if the field code value before this operator and the value after match.
!= string_0 != "test" True if the field code value before this operator and the value after don't match.
> number_0 > 10 True if the field code value before this operator is greater than the value after.
< number_0 < 10 True if the field code value before this operator is less than the value after.
>= number_0 >= 10 True if the field code value before this operator is greater than or equal to the value for the field code after the operator.
<= number_0 <= 10 True if the field code value before this operator is less than or equal to the value for the field code after the operator.
in dropdown_0 in ("A", "B") True if the field code value before this operator matches any value inside the brackets after. This operator can be used for identifying records that have fields with selectable strings, such as drop-down fields and single-choice fields. On the left sample, the operator is used for identifying records with drop-down fields that have selected “A” or “B”.
not in dropdown_0 not in ("A", "B") True if the field code value before this operator doesn't match any value inside the brackets after. This operator can be used for extracting records that have fields with selectable strings, such as drop-down fields and single-choice fields. On the left sample the operator is used for extracting records with drop-down fields that have not selected “A” or “B”.
like Single_line_text_0 like "test" True if the field code value before this operator contains the value after. If the field is an attachment field, the file name and the contents of the file will be checked instead.
not like Single_line_text_0 not like "test" True if the field code value before this operator does not contain the value after.
or number_0 < 10 or number_0 > 20 True if the equation on either side of the or is true. In the left sample, records are identified if the field code number_0 has a value that is less than 10 or more than 20.
and number_0 >= 10 and number_0 <= 20 True if the equation on both sides of the and is true. In the left sample, records are extracted if the field code number_0 has a value that is more than 10 and less than 20.
  • Field codes are to be placed before the operator, not after it.
  • Formulas can be grouped by using "()" brackets, for example: (number_0 >= 10 and number_0 <= 20) or (number_1 >= 100 and number_1 <= 200)

Functions

FUNCTION SAMPLE DESCRIPTION
LOGINUSER() author_ in (LOGINUSER()) Converts to the user initiating the API.
PRIMARY_ORGANIZATION() department in (PRIMARY_ORGANIZATION()) Converts to the Priority Department of the user initiating the API.
NOW() created_datetime = NOW() Converts to the date and time of when the API was initiated.
TODAY() created_datetime = TODAY() Converts to the date when the API was initiated.
FROM_TODAY(number, period) created_datetime < FROM_TODAY(5, "DAYS")

The below periods can be specified:

  • DAYS
  • WEEKS
  • MONTHS
  • YEARS
THIS_WEEK() created_datetime = THIS_WEEK(SUNDAY)

The following days of the week can be set. If nothing is set, it is defaulted to SUNDAY:

  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
LAST_WEEK() created_datetime = LAST_WEEK()

The following days of the week can be set. If nothing is set, it is defaulted to SUNDAY:

  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
THIS_MONTH(number or text) All days of this month
  • created_datetime = THIS_MONTH()

23rd day of this month
  • created_datetime = THIS_MONTH(23)

Last day of this month
  • created_datetime = THIS_MONTH(LAST)
Converts to the month of when the API was initiated.
The following can be specified:
  • Numbers from 1-31 : the day of the month. If the number does not exist, it will convert to the first day of the next month.
  • LAST : the last day of the month.
LAST_MONTH(number or text) All days of the previous month
  • created_datetime = LAST_MONTH()

23rd day of the previous month
  • created_datetime = LAST_MONTH(23)

Last day of the previous month
  • created_datetime = LAST_MONTH(LAST)
Converts to the previous month of when the API was initiated.
The following can be specified:
  • Numbers from 1-31 : the day of the previous month. If the number does not exist, it will convert to the first day of the month to follow.
  • LAST : the last day of the previous month.
THIS_YEAR() created_datetime = THIS_YEAR() Converts to the year of when the API was initiated.

List of operators and functions that can be used with each field.

FIELD OPERATIONS FUNCTIONS
Record Number =   !=   >   <   >=   <=   in   not in  
$id =   !=   >   <   >=   <=   in   not in  
Created by in   not in LOGINUSER()
(*1)
Created datetime =   !=   >   <   >=   <= NOW()
TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK()
THIS_MONTH()
LAST_MONTH()
THIS_YEAR()
Updated by in   not in LOGINUSER()
(*1)
Updated datetime =   !=   >   <   >=   <= NOW()
TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK()
THIS_MONTH()
LAST_MONTH()
THIS_YEAR()
Single-line text =   !=   in   not in   like   not like  
Number =   !=   >   <   >=   <=   in   not in  
Multi-line text like   not like  
Rich text like   not like  
Check box in   not in  
Single choice in   not in  
Drop-down in   not in  
Multi-choice in   not in  
Attachment like   not like  
Date =   !=   >   <   >=   <= TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK()
THIS_MONTH()
LAST_MONTH()
THIS_YEAR()
Time =   !=   >   <   >=   <=  
Date and time =   !=   >   <   >=   <= NOW()
TODAY()
FROM_TODAY()
THIS_WEEK()
LAST_WEEK()
THIS_MONTH()
LAST_MONTH()
THIS_YEAR()
User selection in   not in LOGINUSER()
(*1)
Department selection in   not in PRIMARY_ORGANIZATION()
Group selection in   not in  
Status = != in not in  
Lookup Same as the field it is looking up. Same as the field it is looking up.
Related Records Same as the field of the datasource app field. Same as the field of the datasource app field.
  • (*1) Specify the log in name, Group Code or Department Code. Say that you are looking for records, where the user selection field includes: log in names that include "www" or "xxx", group names that include "yyy" and organization names that include "zzz". This is written as: user_field in (" USER", "www", "xxx", " GROUP", "yyy", " ORGANIZATION", "zzz")
  • If you include Related record fields, or fields that are included in tables inside the query, you will need to replace "=" and "!=" with "in" and "not in" operators.

How to specify the datasource app field inside of the Related records field

Specify the datasource app field in the following way:

field_code_of_Related_records_field.field_code_of_datasource_app_field

Let's say that the field code of your Related records field is "Company_DB", and you are looking for records where the "company_name" field in the Company_DB is equal to "kintone", and the "location" field in the Company_DB includes the characters "San Francisco".

A sample request is as follows:

Company_DB.company_name in ("kintone") and Company_DB.location like "San Francisco"

Options that can be used with the query parameter

The below options can be used in conjunction.

OPTION SAMPLE DESCRIPTION
order by order by Updated_Datetime asc The order of the record output is sorted based on the value of the field code after the option. "asc" will sort the records in ascending order, and "desc" will sort the records in descending order.
limit limit 20 The number of records outputted is determined by the value after this option. The initial number is 100 records, and the maximum is 500.
offset offset 30 This skips outputting the first number of records. The example on the left skips the first 30 records, and outputs from the 31st record. There is no maximum for this value.

Sample Request using Query Strings

The query string is sent by joinining the "app", "query" and "fields" with an "&", and URL encoding the query value.

Let's say that you want to retrieve records that fit the following:

  • an app id of "8"
  • a query of "updated_datetime > "2012-02-03T09:00:00-0800" and updated_datetime < "2012-02-03T10:00:00-0800" order by recordID asc limit 10 offset 0"
  • a field output of fields with field codes of "recordID", "drop_down_field", "updated_datetime"

URL encode the query, and join the other parameters to form a query string.

HTTP Query String

app=8&query=updated_datetime%20%3E%20%222015-03-28T09%3A00%3A00-0800%22%20and%20updated_datetime%20%3C%E3%80%80%222015-04-03T10%3A00%3A00-0800%22%20order%20by%20recordID%20asc%20limit%2010%20offset%200&fields[0]=recordID&fields[1]=drop_down_field&fields[2]=updated_datetime

Request Header

GET /k/v1/records.json?app=8&query=updated_datetime%20%3E%20%222015-03-28T09%3A00%3A00-0800%22%20and%20updated_datetime%20%3C%E3%80%80%222015-04-03T10%3A00%3A00-0800%22%20order%20by%20recordID%20asc%20limit%2010%20offset%200&fields[0]=recordID&fields[1]=drop_down_field&fields[2]=updated_datetime HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=

Sample Request using JSON

Request Header

GET /k/v1/records.json HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json

Body

{
    "app": 8,
    "query": "updated_datetime > \"2012-02-03T09:00:00-0800\" and updated_datetime < \"2012-02-03T10:00:00-0800\" order by $id asc limit 10 offset 0",
    "fields": ["$id", "drop_down_field", "updated_datetime"]
}

Make sure to escape the double quotations around the values with a backslash "\".

Sample Response

A JSON array will be responded with the requested fields of records that fit the query. For field types, check here.

{
    "records": [
        {
            "updated_datetime": {
                "type": "UPDATED_TIME",
                "value": "2015-04-02T01:27:00Z"
            },
            "drop_down_field": {
                "type": "DROP_DOWN",
                "value": "Chocolate"
            },
            "recordID": {
                "type": "RECORD_NUMBER",
                "value": "1"
            }
        },
        {
            "updated_datetime": {
                "type": "UPDATED_TIME",
                "value": "2015-04-02T01:28:00Z"
            },
            "drop_down_field": {
                "type": "DROP_DOWN",
                "value": "Pudding"
            },
            "recordID": {
                "type": "RECORD_NUMBER",
                "value": "2"
            }
        }
    ],
     "totalCount":null
}

JavaScript Samples

kintone REST API Request Example

var body = {
    "app": 20//,
    //"query": "Updated_datetime > \"2012-02-03T09:00:00+0900\" and Updated_datetime < \"2016-02-03T10:00:00+0900\" order by $id asc limit 10 offset 20",
    //"fields": ["$id", "Created_datetime", "Drop_down"]
};
 
kintone.api(kintone.api.url('/k/v1/records', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});

XMLHttpRequest Example

var params = '?app=20'
    //+'&query='
    //encodeURIComponent('Updated_datetime > "2012-02-03T09:00:00+0900" and Updated_datetime < "2016-02-03T10:00:00+0900" order by $id asc limit 10 offset 20') + '&' +
    //encodeURIComponent('fields[0]=$id') + '&' +
    //encodeURIComponent('fields[1]=Created_datetime') + '&' +
    //encodeURIComponent('fields[2]=Drop_down');
var url = 'https://{subdomain}.kintone.com/k/v1/records.json' + params;
  
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();

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.
  • You can specify up to 1000 fields in the request body.
  • For other limitations, check the limitations on this page
Was this article helpful?
1 out of 1 found this helpful
Comments
  • Avatar
    hung anh Trinh

    When using query to retrieve records, if you just added a record matching condition with "like" operator the newly added record seems to be missing.
    For example:
    1) Add record A with field_name = "Hello" using kintone REST API
    2) Immediately after that in the API callback handler get records with query string field_name like "Hello"
    3) The newly added record does not show up

    I guess this behavior happens because Kintone needs to index data for Like operator so it takes a little bit of time.
    Is there any workaround for this problem?
    Thank you very much!

Please sign in to leave a comment.