Retrieves details of multiple records from an App by specifying the App ID and a query string.
This API is planned to limit the maximum offset value to 10,000 in the future, although this date has not been officially decided. If it is necessary to bulk retrieve records using the offset query option, and there is a possibility that the number of records to retrieve may be more than 10,000, use the Add Cursor and Get Cursor APIs instead.
| Method | GET |
| URL | https://{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 |
| Content-Type | application/json (not needed if specifying the query with a query string) |
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 Query Operators and Functions section of this document for more details. 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
Kintone REST API Request Example
curl Sample
Sample Requests (JSON)
Kintone REST API Request Example
curl Sample
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. |
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.
Check the field types documentation for more details on each field type.
Query Operators and Functions
Query Operators
| OPERATOR | SAMPLE | RESPONDED RECORDS |
|---|---|---|
| = | string_0 = "test" | Records where the field line value before the operator and the string after the operator match. |
| != | string_0 != "test" | Records where the field line value before the operator and the string after the operator don't match. |
| > | number_0 > 10 | Records where the field line value before the operator is greater than the value after the operator. |
| < | number_0 < 10 | Records where the field line value before the operator is less than the value after the operator. |
| >= | number_0 >= 10 | Records where the field line value before the operator is greater than or equal to the value after the operator. |
| <= | number_0 <= 10 | Records where the field line value before the operator is less than or equal to the value after the operator. |
| in | dropdown_0 in ("A", "B") | Records where the field line value before the operator matches any of the strings listed in the brackets after the operator. This expression can be used to find what choices have been selected for fields that have multiple selections, such as Drop-down fields and Radio button fields. The sample on the left responds records where the the options "A" or "B" have been selected for the "dropdown_0" field. |
| not in | dropdown_0 not in ("A", "B") | Records where the field line value before the operator don't matches any of the strings listed in the brackets after the operator. This expression can be used to find what choices have not been selected for fields that have multiple selections, such as Drop-down fields and Radio button fields. The sample on the left responds records where the the options "A" or "B" haven't been selected for the "dropdown_0" field. |
| like | Single_line_text_0 like "test" | Records where the string after the operator is included in the field line value before the operator. If an Attachment field is specified, records where the string after the operator is included in the file name or the contents of the file will be responded. |
| not like | Single_line_text_0 not like "test" | Records where the string after the operator is not included in the field line value after the operator. |
| or | number_0 < 10 or number_0 > 20 | Records where the expression on either side of the or is true. The sample on the left responds records where the value of "number_0" is less than 10, or greater than 20. |
| and | number_0 >= 10 and number_0 <= 20 | Records where the expression on both sides of the or is true. The sample on the left responds records where the value of "number_0" is greater than or equal to 10, and less than or equal to 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)
Query 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:
|
| 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:
|
| LAST_WEEK() | created_datetime = LAST_WEEK() |
The following days of the week can be set. If nothing is set, it is defaulted to SUNDAY:
|
| THIS_MONTH(number or text) | All days of this month
23rd day of this month
Last day of this month
|
Converts to the month of when the API was initiated. The following can be specified:
|
| LAST_MONTH(number or text) | All days of the previous month
23rd day of the previous month
Last day of the previous month
|
Converts to the previous month of when the API was initiated. The following can be specified:
|
| THIS_YEAR() | created_datetime = THIS_YEAR() | Converts to the year of when the API was initiated. |
Available Operators and Functions for each field
| FIELD | OPERATIONS | FUNCTIONS |
|---|---|---|
| Record Number | =!=><>=<=innot in | |
| $id | =!=><>=<=innot in | |
| Created by | innot in | LOGINUSER() |
| Created datetime | =!=><>=<= | NOW() TODAY() FROM_TODAY() THIS_WEEK() LAST_WEEK() THIS_MONTH() LAST_MONTH() THIS_YEAR() |
| Updated by | innot in | LOGINUSER() |
| Updated datetime | =!=><>=<= | NOW() TODAY() FROM_TODAY() THIS_WEEK() LAST_WEEK() THIS_MONTH() LAST_MONTH() THIS_YEAR() |
| Text | =!=innot inlikenot like | |
| Number | =!=><>=<=innot in | |
| Text area | likenot like | |
| Rich text | likenot like | |
| Check box | innot in | |
| Radio button | innot in | |
| Drop-down | innot in | |
| Multi-choice | innot in | |
| Attachment | likenot 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 | innot in | LOGINUSER() |
| Department selection | innot in | PRIMARY_ORGANIZATION() |
| Group selection | innot in | |
| Status | =!=innot in | |
| Lookup | Same as the field type it is looking up. | Same as the field type it is looking up. |
| Related Records | Same as the field type of the datasource App field. = and != operators are unusable, and must be replaced with in and not in operators. |
Same as the field type of the datasource App field. |
| Fields within Tables | Same as the field type of the field in the Table. = and != operators are unusable, and must be replaced with in and not in operators. |
Same as the field type of the field in the Table. |
Specifying fields within Related Record fields
- Specify fields within the Related Records field with the following format: relatedrecords.specifiedfield
where relatedrecords is the field line of the Related Records field, and specifiedfield is the field line of the specified field.
Query Options
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 line 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 Queries
Sample 1
- the field Text includes the string "sample"
- the field Text_area includes the string "sample"
- results are listed in descending order of the field Created_datetime
Sample 2
- the field Drop_down includes the values "value1" or "value2"
- the field Multi_choice includes the value "value3" or the field Radio_button includes the value "value4"
Sample 3
- the field Time is greater than the value "10:00"
- the field Time is less than the value "19:00"
- the field Created_datetime is equal to today's date
- results are listed in ascending order of the Record number field
- only up to the first 10 results are outputted
Sample 4
- The user running the API call is included in the field User_selection
- The priority department of the user running the API call is not included in the field Department_selection
Sample 5
- The field company_name within the field Company_DB (a Related Records field) has a value equal to "kintone"
- The field location within the field Company_DB (a Related Records field) includes the string "San Francisco"
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