Saved searches
Save a search and run it again later.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
savedSearchId | path | integer (int64) | required | The saved search's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List saved searches
/v1/saved-searchessaved-searches.list- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
List the saved searches you can see in this workspace: your own, and those shared with you or with the whole workspace.
limit and cursor page the list.
Errors:
400 validation_failed:cursordid not come frompagination.nextCursor(detail codeinvalid_cursor).
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Page size, from 1 to 100. Default 50. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/saved-searches?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of object. Each item has these fields. The response also carries pagination.
Show an example response
The fields and an example are also on this endpoint's Markdown page.
Create a saved search
/v1/saved-searchessaved-searches.create- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
Save a set of Search filters under a name. The saved search belongs to you, in this workspace.
The body takes:
name: the name shown in the list.searchType:Peoplefor a people search,Accountfor a company search, orJobPostsfor a job post search. Any casing works.filtersJson: the search body, as a JSON string. ForJobPostsit must be an object with bothjobFiltersandpeopleFilters, asPOST /v1/job-post-searches/peopletakes them.isShared: true shares the search with the whole workspace. Omitted means true.
The call answers 201 with the saved search and a Location header.
Errors:
400 validation_failed:searchTypeis unknown orfiltersJsonis not valid for it.400 lookalike_not_storable: the filters carry a lookalike filter. A lookalike search is a snapshot, so save its results instead.
Requires Search edit.
curl -X POST "https://api.ken.so/v1/saved-searches" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 201
data is a SavedSearch.
Show the 19 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a saved search
/v1/saved-searches/{savedSearchId}saved-searches.get- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
Get one saved search with its filters and your access to it.
filtersJson holds the saved filters. permissions is your access: read, edit or admin. isValid is false when the saved filters can no longer run, and invalidReason then says why.
Errors:
403 forbidden: the saved search is not shared with you.404 not_found: no saved search has this id.
Requires Search view.
curl -X GET "https://api.ken.so/v1/saved-searches/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SavedSearch.
Show the 19 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a saved search
/v1/saved-searches/{savedSearchId}saved-searches.update- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
Rename a saved search, change its filters, or share it with the whole workspace or stop sharing it.
Send any of name, filtersJson and isShared. Fields you omit keep their value. You need edit access to the saved search, and admin access to change isShared.
Errors:
400 validation_failed:nameis blank orfiltersJsonis not valid.400 lookalike_not_storable: the new filters carry a lookalike filter.403 forbidden: you lack the access this change needs.404 not_found: no saved search has this id.
Requires Search edit.
curl -X PATCH "https://api.ken.so/v1/saved-searches/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SavedSearch.
Show the 19 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a saved search
/v1/saved-searches/{savedSearchId}saved-searches.delete- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
Delete a saved search you created. Only its owner can delete it. The call answers 204 with no body.
Errors:
403 forbidden: you are not the owner.404 not_found: no saved search has this id.
Requires Search edit.
curl -X DELETE "https://api.ken.so/v1/saved-searches/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentRun a saved search
/v1/saved-searches/{savedSearchId}/runsaved-searches.run- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Run a people or company saved search with its saved filters and get the first page of results.
The answer holds savedSearchId, searchType, totalResults and results, the first 25 matches as a people or company search page. Each profile on the page counts against the workspace's daily searchBrowseRows quota. A JobPosts saved search does not run here: send its jobFilters and peopleFilters to POST /v1/job-post-searches/people.
Errors:
400 validation_failed: the saved filters can no longer run, or the saved search is aJobPostssearch.403 forbidden: the saved search is not shared with you.404 not_found: no saved search has this id.429 quota_exceeded: the workspace used its dailysearchBrowseRowsquota.
Requires Search view.
curl -X POST "https://api.ken.so/v1/saved-searches/812/run" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
The body is a SavedSearchRunPeopleResponse or SavedSearchRunCompaniesResponse.
Show an example response
The fields and an example are also on this endpoint's Markdown page.
More in Prospecting data:People and company searchSaved listsSaved list membersSaved list invitesEmail finderFunding roundsJob postingsJob post searchLinkedIn job searchLinkedIn jobsWeb scrapingSocial data lookupsSocial data searchesSocial profile resolutionSocial data recordsSignalsAll resources