API Docs

Add Cursor

Adds a cursor so that large amount of records can be obtained from an App.

MethodPOST
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
app Integer or String Yes The App ID.
fields Array of Strings No The field codes to be included in the response when using the Get Cursor API.

If ignored, all accessible fields in the app will be returned.
query String No The query string that will specify what records will be responded when using the Get Cursor API.

Refer to the Get Records API document for the operators and options that can be specified in the query string.

If ignored, all accessible records from the App will be returned.
size Integer or String No The maximum number of records the Get Cursor API can retrieve from this cursor with one request.

The maximum number is 500 records. If ignored, the default number of records to be retrieved is 100.

Sample Request

JavaScript (using Kintone REST API Request)

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

var body = {
  'app': 1,
  'fields': ['$id', 'Created_by', 'Created_datetime'],
  'query': 'Created_by in (LOGINUSER()) and Created_datetime = TODAY() order by $id asc',
  'size': 500
};
kintone.api(kintone.api.url('/k/v1/records/cursor.json', true), 'POST', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample

1
2
3
4

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

Response Parameters

Parameter Type Description
id String The cursor ID.
totalCount String The total count of records that match the query conditions.

Sample Response

1
2
3
4

{
  "id": "9a9716fe-1394-4677-a1c7-2199a5d28215",
  "totalCount": "123456"
}

Limitations

  • Simultaneous requests cannot be made per domain with this API.
  • The maximum valid cursors per domain is 10.
    If this limit is reached, API calls to add new cursors will fail.
    If one of the following actions occur, the number of valid cursors will be reduced:
    • All records are obtained from an existing cursor
    • A valid cursor is deleted
    • A valid cursor expires
  • Cursors expire after 10 minutes after they are added. If the Get Cursor API specifies a cursor, and there are records yet to be obtained from that cursor, the expiration time will be extended to 10 minutes.
  • This API will timeout after 5 minutes.
    In this case, the API will need to be called again with a simpler query, or a query that will obtain less records.