Search Data

Searches across Kintone, including App records and Thread posts.

MethodPOST
URLhttps://{subdomain}.kintone.com/k/v1/search.json
URL (search all guest spaces the user is a member of)https://{subdomain}.kintone.com/k/guest/v1/search.json
URL (search a specific guest space)https://{subdomain}.kintone.com/k/guest/{GUEST_SPACE_ID}/v1/search.json
Authentication Password Authentication , Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • No permissions are needed.
  • The search only covers data that the authenticated user has permission to view.

Request Parameters

Parameter Type Required Description
query Array Yes The search conditions.
Specify between 1 and 20 conditions.
If multiple conditions are specified, data that meets all conditions is returned.
query[].operator String Yes How the search condition is evaluated.
Specify one of the following values:
  • AND: Returns data that contains all keywords.
  • OR: Returns data that contains any of the keywords.
  • NOT: Returns data that does not contain the keywords.
The search result will be empty if query contains no conditions that use AND or OR.
query[].keywords Array Yes An array of keywords.
Specify between 1 and 20 keywords.
Each keyword must be between 1 and 50 characters.
The maximum limit is 20 keywords across the entire query. The request will fail if this limit is exceeded.
types Array Optional The types of data to search.
Specify any of the following values:
  • RECORD: Records
  • RECORD_COMMENT: Record comments
  • SPACE: Spaces
  • THREAD: Threads
  • THREAD_COMMENT: Thread comments
  • PEOPLE_COMMENT: People comments
  • MESSAGE_COMMENT: Message comments
  • ATTACHMENT: Attachments
If ignored, all data types are searched.
scopes Array Optional The search scopes.
The maximum limit is 20 scopes.
If multiple scopes are specified, data that meets any of the scopes is returned.
scopes[].scope String Yes The type of search scope.
Specify one of the following values:
  • APP: Apps
  • SPACE: Spaces
  • PEOPLE: People
  • MESSAGE: Messages
Required if scopes is specified.
scopes[].ids Array Optional The App IDs or Space IDs.
The maximum limit is 20 IDs.
If scopes[].scope is APP or SPACE, specify App IDs or Space IDs to limit the search scope to those Apps or Spaces. If ignored, all Apps or all Spaces are searched.
This parameter cannot be specified if scopes[].scope is PEOPLE or MESSAGE.
scopes[].codes Array Optional The log in names of users.
The maximum limit is 20 log in names.
If scopes[].scope is PEOPLE or MESSAGE, specify the log in names of People owners or Message partners. This limits the search scope to those People or Messages. If ignored, all People or all Messages are searched.
This parameter cannot be specified if scopes[].scope is APP or SPACE.
excludeScopes Array Optional The scopes to exclude from the search.
The maximum limit is 20 scopes.
If multiple scopes are specified, data that meets all conditions is returned.
If both scopes and excludeScopes are specified, data that meets both conditions is returned. Therefore, excludeScopes takes priority where the two scopes overlap.
excludeScopes[].scope String Yes The type of search scope to exclude.
Specify one of the following values:
  • APP: Apps
  • SPACE: Spaces
  • PEOPLE: People
  • MESSAGE: Messages
Required if excludeScopes is specified.
excludeScopes[].ids Array Optional The App IDs or Space IDs.
The maximum limit is 20 IDs.
If excludeScopes[].scope is APP or SPACE, specify App IDs or Space IDs to exclude those Apps or Spaces from the search scope. If ignored, all Apps or all Spaces are excluded.
This parameter cannot be specified if excludeScopes[].scope is PEOPLE or MESSAGE.
excludeScopes[].codes Array Optional The log in names of users.
The maximum limit is 20 log in names.
If excludeScopes[].scope is PEOPLE or MESSAGE, specify the log in names of People owners or Message partners. This excludes those People or Messages from the search scope. If ignored, all People or all Messages are excluded.
This parameter cannot be specified if excludeScopes[].scope is APP or SPACE.
createdAfter String Optional The earliest created datetime.
Returns data created on or after the specified datetime. This value cannot be later than createdBefore.
For more information on the datetime format, refer to the Kintone REST API Overview article.
createdBefore String Optional The latest created datetime.
Returns data created on or before the specified datetime. This value cannot be earlier than createdAfter.
For more information on the datetime format, refer to the Kintone REST API Overview article.
creators Array Optional The log in names of the creators.
The maximum limit is 20 log in names.
includeSynonyms Boolean or String Optional Whether to include spelling variations, abbreviations, and synonyms of the keywords in the search.
If ignored, this value is false.
sort Object Optional The sort conditions.
sort.by String Optional The sort criteria.
Specify one of the following values:
  • RELEVANCE: Relevance to the keywords
  • CREATED_AT: Created datetime
If ignored, this value is RELEVANCE.
sort.order String Optional The sort direction.
Specify one of the following values:
  • ASC: Ascending order
  • DESC: Descending order
If ignored, this value is DESC.
ASC cannot be specified if sort.by is RELEVANCE.
limit Integer or String Optional The maximum number of results to retrieve.
Specify a value between 1 and 20.
If ignored, this value is 20.
The response may contain fewer results than the limit, even if more matching data remains. Use the nextPageToken property in the response to check whether more matching data remains.
pageToken String Optional The token used to retrieve the next page of search results.
Ignore this parameter in the first request. To retrieve the next page, specify the nextPageToken value from the previous response.
The token expires 30 minutes after it is issued. The request will fail if an expired token is specified.

Sample Request

Request Body (Multiple Keywords)

This request body searches for data that contains both abc and def.

1
2
3
4
5
6
7
8
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc", "def"]
    }
  ]
}

Request Body (Excluded Keywords)

This request body searches for data that contains abc but does not contain def.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    },
    {
      "operator": "NOT",
      "keywords": ["def"]
    }
  ]
}

Request Body (Specified Apps)

This request body searches App 1 and App 2 for attachments that contain abc.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "types": ["ATTACHMENT"],
  "scopes": [
    {
      "scope": "APP",
      "ids": [1, 2]
    }
  ]
}

Request Body (Specified Space)

This request body searches Space 1 for data that contains abc. Data in App 2, which is in Space 1, is excluded.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "scopes": [
    {
      "scope": "SPACE",
      "ids": [1]
    }
  ],
  "excludeScopes": [
    {
      "scope": "APP",
      "ids": [2]
    }
  ]
}

Request Body (Specified Period)

This request body searches for data created by user1 within a specific period. The results are sorted by created datetime in ascending order.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "creators": ["user1"],
  "createdAfter": "2026-05-01T00:00:00-07:00",
  "createdBefore": "2026-05-31T23:59:59-07:00",
  "sort": {
    "by": "CREATED_AT",
    "order": "ASC"
  }
}

JavaScript using kintone.api()

For more information on kintone.api(), refer to the Kintone REST API Request article.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
(async () => {
  const body = {
    query: [
      {
        operator: 'AND',
        keywords: ['abc', 'def']
      }
    ]
  };

  const resp = await kintone.api(kintone.api.url('/k/v1/search.json', true), 'POST', body);
  console.log(resp);
})();

curl Sample

The curl format may vary depending on the environment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST 'https://{subdomain}.kintone.com/k/v1/search.json' \
  -H 'X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [
      {
        "operator": "AND",
        "keywords": ["abc", "def"]
      }
    ]
  }'

Response Parameters

Parameter Type Description
hits Array The search results.
hits[].type String The type of search result.
One of the following values is returned:
  • RECORD
  • RECORD_COMMENT
  • SPACE
  • THREAD
  • THREAD_COMMENT
  • PEOPLE_COMMENT
  • MESSAGE_COMMENT
  • ATTACHMENT
hits[].url String The URL.
If the search result is an attachment, this is the URL of the location the file is attached to.
hits[].snippets Array The text surrounding the keywords.
Up to 3 snippets are returned.
hits[].record Object The record information.
Only included if the search result is a record or a file attached to a record.
hits[].record.appId String The App ID.
hits[].record.appName String The App name.
hits[].record.recordId String The record ID.
hits[].record.recordTitle String The record title.
hits[].record.createdAt String The created datetime.
null is returned if the user does not have view permission for the Created datetime field.
hits[].record.creator Object The creator.
null is returned if the user does not have view permission for the Created by field.
hits[].record.creator.code String The log in name of the creator.
hits[].record.creator.name String The display name of the creator.
hits[].record.matchedFields Array The fields that matched the keywords.
hits[].record.matchedFields[].code String The field code.
hits[].record.matchedFields[].label String The field name.
hits[].record.spaceId String The Space ID.
null is returned if the record is not in a Space App.
hits[].record.spaceName String The Space name.
null is returned if the record is not in a Space App.
hits[].recordComment Object The record comment information.
Only included if the search result is a record comment.
hits[].recordComment.appId String The App ID.
hits[].recordComment.appName String The App name.
hits[].recordComment.recordId String The record ID.
hits[].recordComment.recordTitle String The record title.
hits[].recordComment.commentId String The comment ID.
hits[].recordComment.createdAt String The created datetime.
hits[].recordComment.creator Object The creator.
hits[].recordComment.creator.code String The log in name of the creator.
hits[].recordComment.creator.name String The display name of the creator.
hits[].recordComment.spaceId String The Space ID.
null is returned if the record is not in a Space App.
hits[].recordComment.spaceName String The Space name.
null is returned if the record is not in a Space App.
hits[].space Object The Space information.
Only included if the search result is a Space or a file attached to a Space.
hits[].space.spaceId String The Space ID.
hits[].space.spaceName String The Space name.
hits[].space.createdAt String The created datetime.
hits[].space.creator Object The creator.
hits[].space.creator.code String The log in name of the creator.
hits[].space.creator.name String The display name of the creator.
hits[].thread Object The Thread information.
Only included if the search result is a Thread or a file attached to a Thread.
hits[].thread.threadId String The Thread ID.
hits[].thread.threadName String The Thread name.
hits[].thread.spaceId String The Space ID.
hits[].thread.spaceName String The Space name.
hits[].thread.createdAt String The created datetime.
hits[].thread.creator Object The creator.
hits[].thread.creator.code String The log in name of the creator.
hits[].thread.creator.name String The display name of the creator.
hits[].threadComment Object The Thread comment information.
Only included if the search result is a Thread comment or a file attached to a Thread comment.
hits[].threadComment.commentId String The comment ID.
hits[].threadComment.replyId String The reply ID.
null is returned if the search result is not a reply.
hits[].threadComment.spaceId String The Space ID.
hits[].threadComment.spaceName String The Space name.
hits[].threadComment.threadId String The Thread ID.
hits[].threadComment.threadName String The Thread name.
hits[].threadComment.createdAt String The created datetime.
hits[].threadComment.creator Object The creator.
hits[].threadComment.creator.code String The log in name of the creator.
hits[].threadComment.creator.name String The display name of the creator.
hits[].peopleComment Object The People comment information.
Only included if the search result is a People comment or a file attached to a People comment.
hits[].peopleComment.commentId String The comment ID.
hits[].peopleComment.replyId String The reply ID.
null is returned if the search result is not a reply.
hits[].peopleComment.owner Object The owner of the People.
hits[].peopleComment.owner.code String The log in name of the People owner.
hits[].peopleComment.owner.name String The display name of the People owner.
hits[].peopleComment.createdAt String The created datetime.
hits[].peopleComment.creator Object The creator.
hits[].peopleComment.creator.code String The log in name of the creator.
hits[].peopleComment.creator.name String The display name of the creator.
hits[].messageComment Object The Message comment information.
Only included if the search result is a Message comment or a file attached to a Message comment.
hits[].messageComment.commentId String The comment ID.
hits[].messageComment.createdAt String The created datetime.
hits[].messageComment.creator Object The creator.
This is the user who posted the comment.
hits[].messageComment.creator.code String The log in name of the creator.
hits[].messageComment.creator.name String The display name of the creator.
hits[].messageComment.recipient Object The recipient of the comment.
This is the Message participant who is not the creator.
hits[].messageComment.recipient.code String The log in name of the recipient.
hits[].messageComment.recipient.name String The display name of the recipient.
hits[].attachment Object The attachment information.
Only included if the search result is an attachment.
hits[].attachment.attachedTo String The type of location the file is attached to.
One of the following values is returned:
  • RECORD
  • SPACE
  • THREAD
  • THREAD_COMMENT
  • PEOPLE_COMMENT
  • MESSAGE_COMMENT
hits[].attachment.fileKey String The file key.
hits[].attachment.name String The file name.
hits[].attachment.createdAt String The created datetime.
For files attached to records, null is returned if the user does not have view permission for the Created datetime field.
hits[].attachment.creator Object The creator.
For files attached to records, null is returned if the user does not have view permission for the Created by field.
hits[].attachment.creator.code String The log in name of the creator.
hits[].attachment.creator.name String The display name of the creator.
nextPageToken String The token used to retrieve the next page of search results.
Specify this value in the pageToken request parameter to request the next page.
null is returned if there is no next page.

Sample Response

 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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
  "hits": [
    {
      "type": "RECORD",
      "url": "https://{subdomain}.kintone.com/k/760/show#record=12787",
      "snippets": [
        "New proposal templates have been prepared to support sales activities."
      ],
      "record": {
        "appId": "760",
        "appName": "Activity Reports",
        "recordId": "12787",
        "recordTitle": "Improving Customer Support Efficiency",
        "createdAt": "2024-03-28T09:13:00.000Z",
        "creator": {
          "code": "user1",
          "name": "User 1"
        },
        "matchedFields": [
          {
            "code": "summary",
            "label": "Summary"
          }
        ],
        "spaceId": "18",
        "spaceName": "Sales Division"
      }
    },
    {
      "type": "ATTACHMENT",
      "url": "https://{subdomain}.kintone.com/k/25929/show#record=329",
      "snippets": [
        "The sales support system has been updated to streamline deal management."
      ],
      "record": {
        "appId": "25929",
        "appName": "File Management",
        "recordId": "329",
        "recordTitle": "329",
        "createdAt": "2025-08-04T06:53:00.000Z",
        "creator": {
          "code": "user2",
          "name": "User 2"
        },
        "matchedFields": [],
        "spaceId": null,
        "spaceName": null
      },
      "attachment": {
        "attachedTo": "RECORD",
        "fileKey": "20250804065242B76047BB21494FE5BD4FA54590A50984300",
        "name": "Budget_FY2025.xlsx",
        "createdAt": "2025-08-04T06:53:00.000Z",
        "creator": {
          "code": "user2",
          "name": "User 2"
        }
      }
    },
    {
      "type": "PEOPLE_COMMENT",
      "url": "https://{subdomain}.kintone.com/k/#/people/user/user3/347030/182425",
      "snippets": [
        "The sales support structure is being reviewed to improve customer service quality."
      ],
      "peopleComment": {
        "commentId": "347030",
        "owner": {
          "code": "user3",
          "name": "User 3"
        },
        "createdAt": "2015-12-04T06:31:28.000Z",
        "creator": {
          "code": "user4",
          "name": "User 4"
        },
        "replyId": "182425"
      }
    }
  ],
  "nextPageToken": "e68cc35e9f574dbc9fb7642512a000fb"
}

Limitations

  • Requests to /k/v1/search.json also search guest spaces that the user is a member of. Guest users cannot send requests to this URL.
  • Requests to /k/guest/v1/search.json only search guest spaces that the user is a member of.
  • Requests to /k/guest/{GUEST_SPACE_ID}/v1/search.json only search the specified guest space. The search result will be empty if the user is not a member of the guest space or the guest space does not exist.
  • Search improvements may change the data included in the search results, the order of the results, and the content of hits[].snippets.
  • The maximum limit is 600 requests per minute per domain. If this limit is exceeded, an error response with HTTP status code 429 is returned.