Skip to Content
Prospecting data

Saved searches

Save a search and run it again later.

Prospecting data7 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
savedSearchIdpathinteger (int64)requiredThe saved search's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/saved-searchessaved-searches.list
Permission
Search view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: cursor did not come from pagination.nextCursor (detail code invalid_cursor).

Requires Search view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalPage size, from 1 to 100. Default 50.
cursorquerystringoptionalThe pagination.nextCursor of the previous page. Omit it for the first page.
Request
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

POST/v1/saved-searchessaved-searches.create
Permission
Search edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: People for a people search, Account for a company search, or JobPosts for a job post search. Any casing works.
  • filtersJson: the search body, as a JSON string. For JobPosts it must be an object with both jobFilters and peopleFilters, as POST /v1/job-post-searches/people takes 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: searchType is unknown or filtersJson is 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.

Request
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

GET/v1/saved-searches/{savedSearchId}saved-searches.get
Permission
Search view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/saved-searches/{savedSearchId}saved-searches.update
Permission
Search edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: name is blank or filtersJson is 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.

Request
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

DELETE/v1/saved-searches/{savedSearchId}saved-searches.delete
Permission
Search edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Run a saved search

POST/v1/saved-searches/{savedSearchId}/runsaved-searches.run
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 a JobPosts search.
  • 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 daily searchBrowseRows quota.

Requires Search view.

Request
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.

Share a saved search

POST/v1/saved-searches/{savedSearchId}/sharesaved-searches.share
Permission
Search edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Give a member or the whole workspace access to a saved search, or take that access away. You need admin access to the saved search.

The body takes:

  • action: grant (the default) or revoke.
  • targetType: user for one member, or org for the whole workspace.
  • targetId: the member's user id. Required with user. Omit it with org.
  • permission: read, edit or admin. Required with grant.

Granting or revoking org access also sets isShared. The answer is the saved search after the change.

Errors:

  • 400 validation_failed: a field is missing or not one of the values above.
  • 403 forbidden: you lack admin access to the saved search.
  • 404 not_found: no saved search has this id.

Requires Search edit.

Request
curl -X POST "https://api.ken.so/v1/saved-searches/812/share" \
  -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.


On this page