Segments
Split a campaign's audience into segments, preview their filters, switch them on or off and restore saved versions.
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 |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign's id. |
segmentId | path | integer (int64) | required | The segment'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 a campaign's segments
/v1/campaigns/{campaignId}/segmentssegments.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the campaign's segments in id order, the Default segment included.
Set includeMetrics to false when you need only ids and names. Kenso then skips the contact counts and leaves out contactCount, rawContactCount and readyContactCount.
Errors:
400 validation_failed:limitis out of range, orcursoris invalid.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | optional | Keeps segments whose name contains this text, ignoring case. |
isActive | query | boolean | optional | True keeps active segments, and false keeps inactive ones. Omit it to get both. |
limit | query | integer (int32) | optional | Segments per page, from 1 to 200. Defaults to 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
includeMetrics | query | boolean | optional | Set to false to skip the contact counts, which leaves out contactCount, rawContactCount and readyContactCount. Defaults to true. |
curl -X GET "https://api.ken.so/v1/campaigns/812/segments?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 Segment. Each item has these fields. The response also carries pagination.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a segment
/v1/campaigns/{campaignId}/segmentssegments.create- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Adds a segment to the campaign and returns it, with its URL in the Location header. The new segment starts with a copy of the Default segment's email sequence, or of the campaign's email sequence when the Default segment has none of its own.
On an A/B test campaign, every new segment is an ab_test segment. An ab_test segment needs abTestPercentage from 1 to 100, and other types cannot have one. Only a manual segment can have filterCriteria. sortOrder defaults to one more than the campaign's highest.
Errors:
400 validation_failed:nameis missing, or another segment in the campaign already has it.400 validation_failed:segmentationTypeis notmanual,aiorab_test, or isab_teston a campaign that is not an A/B test.400 validation_failed:abTestPercentageis missing on anab_testsegment, set on another type, or out of range.400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the active segments' percentages would not add up to 100.400 validation_failed:filterCriteriais set on a segment that is notmanual, breaks a filter rule, or has keys but none of them is a filter field.400 validation_failed:filterCriteriausesbehaviorTagsorbehaviorTagsExcludewhile behavior signals are off for the workspace.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | The segment's name. Required, and unique within the campaign. |
description | string | optional | A free-text description. Omit it for none. |
segmentationType | string | optional | manual, ai or ab_test. On an A/B test campaign the segment is always ab_test, and on any other campaign ab_test is refused. Omit it to create a segment with no type, which cannot have filters. |
abTestPercentage | integer (int32) | optional | The share of the campaign's contacts the segment takes, from 1 to 100. Required on an ab_test segment and refused on any other type. |
sortOrder | integer (int32) | optional | The segment's display position among the campaign's segments. Defaults to one more than the campaign's highest. |
filterCriteria | CampaignSegmentFilterCriteria | optional | The segment's filters. Only a manual segment can have them. Omit it for none. |
curl -X POST "https://api.ken.so/v1/campaigns/812/segments" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Engineering leaders",
"description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
"segmentationType": "ai",
"sortOrder": 1
}'Response 201
data is a Segment.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a segment
/v1/segments/{segmentId}segments.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one segment with its filters and contact counts.
Errors:
404 not_found: the segment does not exist in this workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/segments/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 Segment.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a segment
/v1/segments/{segmentId}segments.update- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Changes the fields you send and leaves the others as they are. A JSON null clears description or abTestPercentage. An update does not save a version. Use POST /v1/segments/{segmentId}/versions to save one.
A filterCriteria object replaces all of the segment's filters, and an empty object clears them. A null filterCriteria leaves the filters as they are. A segment with filters cannot change to ai or ab_test until you clear its filters.
Errors:
400 validation_failed:nameis empty, or another segment in the campaign already has it.400 validation_failed:segmentationTypeis notmanual,aiorab_test, or the segment has filters and the new type is notmanual.400 validation_failed:abTestPercentageis out of range, missing on anab_testsegment, or set on another type.400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the active segments' percentages would not add up to 100.400 validation_failed:filterCriteriais set on a segment that is notmanual, breaks a filter rule, or has keys but none of them is a filter field.400 validation_failed:filterCriteriaadds a behavior tag the segment does not have while behavior signals are off for the workspace.404 not_found: the segment does not exist in this workspace.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | A new name, unique within the campaign. Cannot be empty. |
description | string | optional | A new description. Null clears it. |
segmentationType | string | optional | manual, ai or ab_test. A segment with filters can change only to manual. |
abTestPercentage | integer (int32) | optional | The share of the campaign's contacts an ab_test segment takes, from 1 to 100. Null clears it, which only a segment of another type can do. |
sortOrder | integer (int32) | optional | The segment's display position among the campaign's segments. |
filterCriteria | CampaignSegmentFilterCriteria | optional | Replaces all of the segment's filters. An empty object clears them, and null leaves them as they are. Field names match in any letter case. |
curl -X PATCH "https://api.ken.so/v1/segments/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Engineering leaders",
"description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
"segmentationType": "manual",
"sortOrder": 1,
"filterCriteria": {
"titles": [
"VP of Engineering",
"Head of Engineering"
],
"seniorityLevels": [
"VP",
"Director"
],
"functions": [
"Engineering"
],
"profileCountries": [
"United States"
],
"industries": [
"Computer Software"
],
"companyHeadcount": {
"min": 50,
"max": 500
}
}
}'Response 200
data is a Segment.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a segment
/v1/segments/{segmentId}segments.delete- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Deletes the segment with its email sequence, LinkedIn steps and AI prompts. Its contacts move to the Default segment or, on an A/B test campaign, to the remaining active ab_test segments. Contacts keep their AI output.
Errors:
400 validation_failed: the segment is the Default segment.400 validation_failed: its contacts would move to the Default segment, and the segment has an email or LinkedIn sequence on a channel where neither the Default segment nor the campaign has one. Save that sequence on the Default segment, or delete it from this segment, first.400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the remaining active segments' percentages would not add up to 100.404 not_found: the segment does not exist in this workspace.
Requires Campaigns edit.
curl -X DELETE "https://api.ken.so/v1/segments/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 ContentPreview a segment filter
/v1/campaigns/{campaignId}/segments/previewsegments.preview- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Counts the campaign's contacts that match a filter and returns up to 10 of them, newest first, with the filter options in filterOptions. Nothing is saved.
Send no body to get only the filter options, with the counts at 0. GET /v1/segments/filter-options returns the same options without a campaign.
The preview looks at contacts with no segment and contacts in the Default segment, plus the contacts of segmentId when you pass it. Contacts on the do-not-contact list are left out unless the filter sets doNotContact to true.
Errors:
400 validation_failed: the body is an empty object, has keys but none of them is a filter field, or breaks a filter rule.400 validation_failed: the filter usesbehaviorTagsorbehaviorTagsExcludewhile behavior signals are off for the workspace.404 not_found: the campaign does not exist in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
segmentId | query | integer (int64) | optional | A segment of the campaign whose contacts the preview also looks at. Omit it to look only at contacts with no segment and the Default segment's contacts. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
fullName | StringFilter | optional | Matches the contact's full name. |
titles | array of string | optional | Keeps contacts whose job title contains any of these values, ignoring case. |
excludeTitles | array of string | optional | Drops contacts whose job title contains any of these values, ignoring case. Contacts with no title stay. |
lastJobTitle | StringFilter | optional | Matches the contact's last job title. |
headlines | array of string | optional | Keeps contacts whose headline contains any of these values, ignoring case. |
excludeHeadlines | array of string | optional | Drops contacts whose headline contains any of these values, ignoring case. Contacts with no headline stay. |
summaryContains | string | optional | Keeps contacts whose profile summary contains this text, ignoring case. |
seniorityLevels | array of string | optional | Keeps contacts whose seniority level is exactly one of these values. seniorityLevels in GET /v1/segments/filter-options lists the values. |
excludeSeniorityLevels | array of string | optional | Drops contacts whose seniority level is exactly one of these values. Contacts with no seniority level stay. |
functions | array of string | optional | Keeps contacts whose job function is exactly one of these values. functions in GET /v1/segments/filter-options lists the values. |
excludeFunctions | array of string | optional | Drops contacts whose job function is exactly one of these values. Contacts with no function stay. |
employmentTypes | array of string | optional | Keeps contacts whose employment type is exactly one of these values. employmentTypes in GET /v1/segments/filter-options lists the values. |
isDecisionMaker | boolean | optional | True keeps only contacts marked as decision makers, and false keeps only the others. |
changedJobRecently | boolean | optional | True keeps only contacts marked as having changed jobs recently, and false keeps only the others. |
yearsOfExperience | FloatRange | optional | The contact's total years of work experience. Contacts with no value do not match a bound. |
yearsInCurrentRole | FloatRange | optional | The contact's years in their current role. Contacts with no value do not match a bound. |
yearsInCurrentCompany | FloatRange | optional | The contact's years at their current company. Contacts with no value do not match a bound. |
profileCountries | array of string | optional | Keeps contacts whose country is exactly one of these values. |
excludeProfileCountries | array of string | optional | Drops contacts whose country is exactly one of these values. Contacts with no country stay. |
profileState | string | optional | Keeps contacts whose state or region contains this text, ignoring case. |
profileCity | string | optional | Keeps contacts whose city contains this text, ignoring case. |
skillsContains | string | optional | Keeps contacts whose skills contain this text, ignoring case. |
certificationsContains | string | optional | Keeps contacts whose certifications contain this text, ignoring case. |
languages | array of string | optional | Keeps contacts whose languages contain any of these values, ignoring case, such as French. |
emailValidity | array of string | optional | Keeps contacts with at least one email address in any of these validity states. Use the values of emailValidity in GET /v1/segments/filter-options. Kenso refuses a value it does not recognize. |
emailProviders | array of string | optional | Keeps contacts with at least one email address found by any of these sources. Use the values of emailProviders in GET /v1/segments/filter-options. Kenso refuses a value it does not recognize. |
excludeEmailProviders | array of string | optional | Drops contacts with an email address found by any of these sources. Use the values of emailProviders in GET /v1/segments/filter-options. Kenso refuses a value it does not recognize. |
isPersonalEmail | boolean | optional | True keeps contacts with at least one personal email address. False keeps contacts with at least one email address that is not personal. |
hasLinkedInUrl | boolean | optional | True keeps only contacts with a LinkedIn profile URL, and false keeps only contacts without one. |
hasPhone | boolean | optional | True keeps only contacts with a phone number, and false keeps only contacts without one. |
hasValidPhone | boolean | optional | True keeps only contacts with a phone number checked as valid, and false keeps only contacts without a valid phone number. |
companyNames | array of string | optional | Keeps contacts whose company name contains any of these values, ignoring case. |
excludeCompanyNames | array of string | optional | Drops contacts whose company name contains any of these values, ignoring case. Contacts with no company stay. |
companyDomainContains | string | optional | Keeps contacts whose company domain contains this text, ignoring case. |
companyDescriptionContains | string | optional | Keeps contacts whose company description contains this text, ignoring case. |
companySpecialitiesContains | string | optional | Keeps contacts whose company specialities contain this text, ignoring case. |
industries | array of string | optional | Keeps contacts whose company industry is one of these values, ignoring case. industries in GET /v1/segments/filter-options lists common values. |
excludeIndustries | array of string | optional | Drops contacts whose company industry is one of these values, ignoring case. Contacts with no industry stay. |
companyHeadcount | IntRange | optional | The company's number of employees. Contacts with no company do not match a bound. |
companyFollowers | IntRange | optional | The company's number of followers. Contacts with no company do not match a bound. |
companyFoundedYear | IntRange | optional | The year the company was founded, each bound from 0 to 32767. Contacts with no company do not match a bound. |
companyTypes | array of string | optional | Keeps contacts whose company type is exactly one of these values. companyTypes in GET /v1/segments/filter-options lists the values. |
lastFundingRounds | array of string | optional | Keeps contacts whose company's last funding round contains any of these values, ignoring case. lastFundingRounds in GET /v1/segments/filter-options lists the values. |
totalFunding | LongRange | optional | The company's total funding. Contacts with no company do not match a bound. |
technologies | array of string | optional | Keeps contacts whose company uses any of these technologies. A value must match one whole entry of the company's technology list. |
excludeTechnologies | array of string | optional | Drops contacts whose company uses any of these technologies, matched the same way as technologies. Contacts with no company or technology list stay. |
companyHqCountries | array of string | optional | Keeps contacts whose company headquarters country is exactly one of these values. |
excludeCompanyHqCountries | array of string | optional | Drops contacts whose company headquarters country is exactly one of these values. Contacts with no company or headquarters country stay. |
companyHqState | string | optional | Keeps contacts whose company headquarters state or region contains this text, ignoring case. |
companyHqCity | string | optional | Keeps contacts whose company headquarters city contains this text, ignoring case. |
doNotContact | boolean | optional | True keeps only contacts marked do not contact, and false keeps only the others. |
createdAt | DateRange | optional | When the contact was added. |
totalClicks | IntRange | optional | The number of email link clicks the contact made, summed across all campaigns. A contact with no clicks counts as 0. |
leadQualityScore | IntRange | optional | The lead quality score Ken gave the contact in its campaign, each bound from 1 to 10. Contacts without a score do not match. |
behaviorTags | array of string | optional | Keeps contacts that carry any of these behavior tags, such as cold_responder or best_window:weekday_morning. Needs the behavior signals feature. At most 50 tags, and tags tied to one email address or company cannot be filtered on. |
behaviorTagsExclude | array of string | optional | Drops contacts that carry any of these behavior tags. Needs the behavior signals feature, with the same tag rules as behaviorTags. |
aiVariableFilters | array of AiVariableFilter | optional | Rules on the output of the campaign's AI prompts. A contact must match every rule. At most 50 rules. Kenso drops a rule without a promptId or operator, or a contains or not_contains rule without a value, and reports no error. |
customVariableFilters | array of CustomVariableFilter | optional | Rules on the contact's campaign custom variables. A contact must match every rule. At most 50 rules. Kenso drops a rule without a variableKey or operator, or a rule that needs a value and has none, and reports no error. |
curl -X POST "https://api.ken.so/v1/campaigns/812/segments/preview" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"titles": [
"VP of Engineering",
"Head of Engineering"
],
"seniorityLevels": [
"VP",
"Director"
],
"functions": [
"Engineering"
],
"profileCountries": [
"United States"
],
"industries": [
"Computer Software"
],
"companyHeadcount": {
"min": 50,
"max": 500
}
}'Response 200
data is a SegmentPreview.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Activate a segment
/v1/segments/{segmentId}/activatesegments.activate- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Turns the segment back on and saves a segment version. Activating a segment that is already active changes nothing.
Errors:
400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the active segments' percentages would not add up to 100.404 not_found: the segment does not exist in this workspace.409 conflict: another version save for this segment is running. Retry shortly.
Requires Campaigns edit.
curl -X POST "https://api.ken.so/v1/segments/812/activate" \
-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 Segment.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Deactivate a segment
/v1/segments/{segmentId}/deactivatesegments.deactivate- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Turns the segment off and saves a segment version. Kenso does not send to contacts in an inactive segment. Deactivating a segment that is already inactive changes nothing.
Errors:
400 validation_failed: the segment is the Default segment.400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the remaining active segments' percentages would not add up to 100.404 not_found: the segment does not exist in this workspace.409 conflict: another version save for this segment is running. Retry shortly.
Requires Campaigns edit.
curl -X POST "https://api.ken.so/v1/segments/812/deactivate" \
-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 Segment.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get the segment filter options
/v1/segments/filter-optionssegments.get-filter-options- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the values to offer for the list filters of a segment: seniority levels, functions, industries, company types, employment types, funding rounds, technologies, email validity, email providers and languages. Each option has the value to send in the filter and a label to show. The options are the same for every workspace.
industries and languages list common values only, and their filters also accept other text. technologies has no options. POST /v1/campaigns/{campaignId}/segments/preview returns the same options in filterOptions.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/segments/filter-options" \
-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 SegmentFilterMetadata.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a segment's provider tracks
/v1/segments/{segmentId}/provider-trackssegments.get-provider-tracks- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the three provider tracks of one segment: google, microsoft and other (everyone else). A contact's track comes from the mail provider of the address Kenso emails; a contact whose provider is not known yet counts under google. Recipients on Google get plain text; recipients on Microsoft get the email as written.
Each track has its leadCount (contacts that can still get an email; at most 100,000 are read, past that isPartial is true) and sequenceSegmentId, the segment whose /v1/segments/{segmentId}/email-sequence holds the track's copy. hasOwnSequence is false while the track still shares the segment's sequence, and sameAs lists the other tracks that share it. enabled is false when the campaign is not on provider tracks; its sends then go out as before.
Errors:
400 validation_failed: the workspace does not have provider tracks (detail codefeature_disabled).404 not_found: the segment does not exist in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
segmentId | path | integer (int64) | required | Id of the segment. |
curl -X GET "https://api.ken.so/v1/segments/812/provider-tracks" \
-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 ProviderTracks.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Give a provider track its own sequence, or share the segment's
/v1/segments/{segmentId}/provider-tracks/{track}segments.set-provider-track- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Sets the sequence one provider track of a segment sends. The track is google, microsoft or other (everyone else). Format follows the recipient's mail provider: a recipient on Google gets plain text, a recipient on Microsoft gets the email as written.
Send { "sequence": "own" } to give the track its own copy of the segment's email sequence: read and replace that copy with /v1/segments/{segmentId}/email-sequence on the track's sequenceSegmentId. Editing one track's copy never changes another's. The segment needs an email sequence of its own first: a segment that sends the campaign's emails answers no_sequence, so save those emails onto the segment with PUT /v1/segments/{segmentId}/email-sequence before you ask for a copy. Send { "sequence": "shared" } to drop the track's copy: its contacts continue on the segment's sequence at the same step. Both are safe to repeat. Returns the tracks as GET /v1/segments/{segmentId}/provider-tracks does.
Errors:
400 validation_failed: detail codefeature_disabled(the workspace does not have provider tracks),invalid_track,invalid_sequence,no_sequence(the segment has no email sequence to copy) orsequence_has_conditions(a sequence with conditions has one copy for all tracks).404 not_found: the segment does not exist in this workspace.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
segmentId | path | integer (int64) | required | Id of the segment. |
track | path | string | required | The provider track: google, microsoft or other. |
Request body
application/json, optional.
The sequence the track sends: own or shared.
| Field | Type | Required | Description |
|---|---|---|---|
sequence | string | optional | own gives the track its own copy of the segment's sequence; shared drops that copy. |
curl -X PUT "https://api.ken.so/v1/segments/812/provider-tracks/google" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"sequence": "own"
}'Response 200
data is a ProviderTracks.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Apply one provider track's copy to all tracks
/v1/segments/{segmentId}/provider-tracks/{track}/apply-to-allsegments.apply-provider-track-to-all- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Makes every provider track of the segment send the same copy. When the named track has its own sequence, the segment's email sequence is replaced with it, with every check a sequence save runs; then every track's own copy is dropped, so all three tracks share the segment's sequence again. When the named track already shares the segment's sequence, only the other tracks' own copies are dropped. Contacts mid-sequence continue at the same step. Returns the tracks as GET /v1/segments/{segmentId}/provider-tracks does.
Errors:
400 validation_failed: detail codefeature_disabled,invalid_track,no_sequence, or the detail codes of a sequence save; nothing is dropped when the save is refused.404 not_found: the segment does not exist in this workspace.409 conflict: the segment's email sequence changed while it was being replaced; nothing is dropped.503 service_unavailable: a sequence could not be read or saved; nothing is dropped. Try again.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
segmentId | path | integer (int64) | required | Id of the segment. |
track | path | string | required | The provider track whose copy all tracks get: google, microsoft or other. |
curl -X POST "https://api.ken.so/v1/segments/812/provider-tracks/google/apply-to-all" \
-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 ProviderTracks.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a segment's versions
/v1/segments/{segmentId}/versionssegments.list-versions- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the segment's saved versions, newest first. Kenso adds a version when you save one, activate or deactivate the segment, or restore a version. Updating the segment does not add one.
Errors:
400 validation_failed:limitis out of range, orcursoris invalid.404 not_found: the segment does not exist in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Versions per page, from 1 to 100. Defaults to 20. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/segments/812/versions?limit=20" \
-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 SegmentVersion. Each item has these fields. The response also carries pagination.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Save a segment version
/v1/segments/{segmentId}/versionssegments.save-version- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Applies the fields you send to the live segment, then saves a version of the result. Send no body to save the segment as it is.
The body takes the fields of PATCH /v1/segments/{segmentId}, with the same rules, plus sourceVersionId. Absent fields keep the live segment's value, or that version's value when you pass sourceVersionId. A JSON null clears description or abTestPercentage. When the segment is saved but Kenso cannot record the version, version is null and versionWarning says why.
Errors:
400 validation_failed: a field breaks a rule ofPATCH /v1/segments/{segmentId}.400 validation_failed:sourceVersionIdis 0.404 not_found: the segment does not exist in this workspace, orsourceVersionIdis not one of its versions.409 conflict: another version save for this segment is running. Retry shortly.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
sourceVersionId | integer (int64) | optional | The id of a saved version of this segment to start from. Fields you leave out take that version's values. Omit it to start from the live segment. |
name | string | optional | A new name, unique within the campaign. Cannot be empty. |
description | string | optional | A new description. Null clears it. |
segmentationType | string | optional | manual, ai or ab_test. A segment with filters can change only to manual. |
abTestPercentage | integer (int32) | optional | The share of the campaign's contacts an ab_test segment takes, from 1 to 100. Null clears it, which only a segment of another type can do. |
sortOrder | integer (int32) | optional | The segment's display position among the campaign's segments. |
filterCriteria | CampaignSegmentFilterCriteria | optional | Replaces all of the segment's filters. An empty object clears them, and null leaves them as they are. Field names match in any letter case. |
curl -X POST "https://api.ken.so/v1/segments/812/versions" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Engineering leaders",
"description": "VPs and heads of engineering at B2B SaaS companies with 50 to 500 employees.",
"segmentationType": "manual",
"sortOrder": 1,
"filterCriteria": {
"titles": [
"VP of Engineering",
"Head of Engineering"
],
"seniorityLevels": [
"VP",
"Director"
],
"functions": [
"Engineering"
],
"profileCountries": [
"United States"
],
"industries": [
"Computer Software"
],
"companyHeadcount": {
"min": 50,
"max": 500
}
},
"sourceVersionId": 1880
}'Response 200
data is a SegmentVersionSave.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a segment version
/v1/segments/{segmentId}/versions/{versionId}segments.get-version- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one saved version with snapshot, a copy of the segment's settings and filters as they were saved.
Errors:
404 not_found: the segment does not exist in this workspace, or the version is not one of its versions.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
versionId | path | integer (int64) | required | The version's id, from the list of versions. |
curl -X GET "https://api.ken.so/v1/segments/812/versions/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 SegmentVersionDetail.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Restore a segment version
/v1/segments/{segmentId}/versions/{versionId}/restoresegments.restore-version- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Brings the segment back to a saved version and saves a new version that records the restore. Kenso also brings back the segment's AI prompts, email sequence and LinkedIn sequence, each to the latest version it had when the target version was saved. children reports what happened to each of them.
Set dryRun to true to see what a restore would do without changing anything. The response then carries the target version, its snapshot, and each child with the snapshot it would restore.
When the restore would clear AI output already generated for the campaign, Kenso answers 409 conflict with error.impact. Send the call again with confirm set to true to go ahead.
Errors:
400 validation_failed: a restored step breaks today's sequence rules.400 validation_failed: on an A/B test campaign that is scheduled, launching, sending or paused, the active segments' percentages would not add up to 100.404 not_found: the segment does not exist in this workspace, or the version is not one of its versions.409 conflictwitherror.impact: the restore would clear AI output andconfirmis not true.409 conflict: another version save for this segment is running. Retry shortly.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
versionId | path | integer (int64) | required | The id of the version to restore. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | optional | Set to true to restore even when the restore would clear AI output already generated for the campaign. Without it, such a restore answers 409 conflict with error.impact. Defaults to false. |
dryRun | boolean | optional | Set to true to see what the restore would do without changing anything. Defaults to false. |
curl -X POST "https://api.ken.so/v1/segments/812/versions/812/restore" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"confirm": false,
"dryRun": true
}'Response 200
data is a SegmentRestore.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Campaigns:CampaignsEmail sequencesLinkedIn sequencesSegment email sequencesSegment LinkedIn sequencesSequence variablesSequences with conditionsSequence importLead listsShare linksClient approvalsSending capacityAuto-pausesCampaign languagesLocalized stepsText translationMarket packsCountry complianceCampaign imagesAll resources