Get Cursor

Retrieves multiple records from an App by specifying the cursor ID.

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/records/cursor.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/records/cursor.json
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json

Contents

Permissions

The user or API Token must have permission to view the records.

Request Parameters

Parameter Value Required Description
id String Yes The cursor ID.

Sample Request

JavaScript (using
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
var body = {
  'id': '9a9716fe-1394-4677-a1c7-2199a5d28215'
};
kintone.api(kintone.api.url('/k/v1/records/cursor.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/cursor.json' \
  -H 'X-Cybozu-API-Token: {APIToken}' \
  -H 'Content-Type: application/json' \
  -d '{"id": "9a9716fe-1394-4677-a1c7-2199a5d28215"}'

Response Parameters

Parameter Type Description
records Array An array of objects that includes field data of records that match the query.
The response is the same as the response for the Get Records API.
next Boolean States whether there are more records that can be acquired from the cursor.
  • true: There are still records to be acquired.
  • false: There are no more records to be acquired.
Run this API again with the same parameters to obtain the next set of records.
The cursor will remain valid until all records have been obtained.

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "records": [
    {
      "$id": {
        "type": "__ID__",
        "value": "1"
      },
      "Created_by": {
        "type": "CREATOR",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "Created_datetime": {
        "type": "CREATED_TIME",
        "value": "2019-05-23T04:50:00Z"
      }
    }
  ],
  "next": false
}

Limitations

  • The Get Cursor API returns records that match the query at the timing when the Add Cursor API is called.
    However, the Get Cursor API returns the field values of records at the timing the Get Cursor API is called.

  • In the case where new permission settings are applied to the App after a cursor is added, the Get Cursor API may return records that should not match the query with the new permissions. In this case, values within fields with no view permissions cannot be seen in the response.

  • As the field values obtained is dependent on when the Get Cursor API is called, the obtained values from localized fields may vary depending on the API initiator's language settings.

  • There may be cases when the next set of records obtained (when the next parameter is true) is empty, if records are deleted or have new permissions settings applied during the Get Cursor API requests.

  • The cursor will automatically be deleted when it responds false for the next parameter. Any further requests will result in a 404 error response.

  • If the query string includes like and not like operators, the search will be stopped after it matches 100,000 records. In this case, "x-cybozu-warning : Filter aborted because of too many search results." will be included in the response header.

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.
    • 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 (External link) .