Skip to Content
Campaigns

Segments

Split a campaign's audience into segments, preview their filters, switch them on or off and restore saved versions.

Campaigns16 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
campaignIdpathinteger (int64)requiredThe campaign's id.
segmentIdpathinteger (int64)requiredThe segment'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 a campaign's segments

GET/v1/campaigns/{campaignId}/segmentssegments.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is out of range, or cursor is invalid.
  • 404 not_found: the campaign does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
qquerystringoptionalKeeps segments whose name contains this text, ignoring case.
isActivequerybooleanoptionalTrue keeps active segments, and false keeps inactive ones. Omit it to get both.
limitqueryinteger (int32)optionalSegments per page, from 1 to 200. Defaults to 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
includeMetricsquerybooleanoptionalSet to false to skip the contact counts, which leaves out contactCount, rawContactCount and readyContactCount. Defaults to true.
Request
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

POST/v1/campaigns/{campaignId}/segmentssegments.create
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: name is missing, or another segment in the campaign already has it.
  • 400 validation_failed: segmentationType is not manual, ai or ab_test, or is ab_test on a campaign that is not an A/B test.
  • 400 validation_failed: abTestPercentage is missing on an ab_test segment, 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: filterCriteria is set on a segment that is not manual, breaks a filter rule, or has keys but none of them is a filter field.
  • 400 validation_failed: filterCriteria uses behaviorTags or behaviorTagsExclude while 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.

FieldTypeRequiredDescription
namestringrequiredThe segment's name. Required, and unique within the campaign.
descriptionstringoptionalA free-text description. Omit it for none.
segmentationTypestringoptionalmanual, 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.
abTestPercentageinteger (int32)optionalThe 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.
sortOrderinteger (int32)optionalThe segment's display position among the campaign's segments. Defaults to one more than the campaign's highest.
filterCriteriaCampaignSegmentFilterCriteriaoptionalThe segment's filters. Only a manual segment can have them. Omit it for none.
Request
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

GET/v1/segments/{segmentId}segments.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns one segment with its filters and contact counts.

Errors:

  • 404 not_found: the segment does not exist in this workspace.

Requires Campaigns view.

Request
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

PATCH/v1/segments/{segmentId}segments.update
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: name is empty, or another segment in the campaign already has it.
  • 400 validation_failed: segmentationType is not manual, ai or ab_test, or the segment has filters and the new type is not manual.
  • 400 validation_failed: abTestPercentage is out of range, missing on an ab_test segment, 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: filterCriteria is set on a segment that is not manual, breaks a filter rule, or has keys but none of them is a filter field.
  • 400 validation_failed: filterCriteria adds 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.

FieldTypeRequiredDescription
namestringoptionalA new name, unique within the campaign. Cannot be empty.
descriptionstringoptionalA new description. Null clears it.
segmentationTypestringoptionalmanual, ai or ab_test. A segment with filters can change only to manual.
abTestPercentageinteger (int32)optionalThe 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.
sortOrderinteger (int32)optionalThe segment's display position among the campaign's segments.
filterCriteriaCampaignSegmentFilterCriteriaoptionalReplaces 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.
Request
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

DELETE/v1/segments/{segmentId}segments.delete
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Preview a segment filter

POST/v1/campaigns/{campaignId}/segments/previewsegments.preview
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 uses behaviorTags or behaviorTagsExclude while behavior signals are off for the workspace.
  • 404 not_found: the campaign does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
segmentIdqueryinteger (int64)optionalA 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.

FieldTypeRequiredDescription
fullNameStringFilteroptionalMatches the contact's full name.
titlesarray of stringoptionalKeeps contacts whose job title contains any of these values, ignoring case.
excludeTitlesarray of stringoptionalDrops contacts whose job title contains any of these values, ignoring case. Contacts with no title stay.
lastJobTitleStringFilteroptionalMatches the contact's last job title.
headlinesarray of stringoptionalKeeps contacts whose headline contains any of these values, ignoring case.
excludeHeadlinesarray of stringoptionalDrops contacts whose headline contains any of these values, ignoring case. Contacts with no headline stay.
summaryContainsstringoptionalKeeps contacts whose profile summary contains this text, ignoring case.
seniorityLevelsarray of stringoptionalKeeps contacts whose seniority level is exactly one of these values. seniorityLevels in GET /v1/segments/filter-options lists the values.
excludeSeniorityLevelsarray of stringoptionalDrops contacts whose seniority level is exactly one of these values. Contacts with no seniority level stay.
functionsarray of stringoptionalKeeps contacts whose job function is exactly one of these values. functions in GET /v1/segments/filter-options lists the values.
excludeFunctionsarray of stringoptionalDrops contacts whose job function is exactly one of these values. Contacts with no function stay.
employmentTypesarray of stringoptionalKeeps contacts whose employment type is exactly one of these values. employmentTypes in GET /v1/segments/filter-options lists the values.
isDecisionMakerbooleanoptionalTrue keeps only contacts marked as decision makers, and false keeps only the others.
changedJobRecentlybooleanoptionalTrue keeps only contacts marked as having changed jobs recently, and false keeps only the others.
yearsOfExperienceFloatRangeoptionalThe contact's total years of work experience. Contacts with no value do not match a bound.
yearsInCurrentRoleFloatRangeoptionalThe contact's years in their current role. Contacts with no value do not match a bound.
yearsInCurrentCompanyFloatRangeoptionalThe contact's years at their current company. Contacts with no value do not match a bound.
profileCountriesarray of stringoptionalKeeps contacts whose country is exactly one of these values.
excludeProfileCountriesarray of stringoptionalDrops contacts whose country is exactly one of these values. Contacts with no country stay.
profileStatestringoptionalKeeps contacts whose state or region contains this text, ignoring case.
profileCitystringoptionalKeeps contacts whose city contains this text, ignoring case.
skillsContainsstringoptionalKeeps contacts whose skills contain this text, ignoring case.
certificationsContainsstringoptionalKeeps contacts whose certifications contain this text, ignoring case.
languagesarray of stringoptionalKeeps contacts whose languages contain any of these values, ignoring case, such as French.
emailValidityarray of stringoptionalKeeps 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.
emailProvidersarray of stringoptionalKeeps 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.
excludeEmailProvidersarray of stringoptionalDrops 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.
isPersonalEmailbooleanoptionalTrue keeps contacts with at least one personal email address. False keeps contacts with at least one email address that is not personal.
hasLinkedInUrlbooleanoptionalTrue keeps only contacts with a LinkedIn profile URL, and false keeps only contacts without one.
hasPhonebooleanoptionalTrue keeps only contacts with a phone number, and false keeps only contacts without one.
hasValidPhonebooleanoptionalTrue keeps only contacts with a phone number checked as valid, and false keeps only contacts without a valid phone number.
companyNamesarray of stringoptionalKeeps contacts whose company name contains any of these values, ignoring case.
excludeCompanyNamesarray of stringoptionalDrops contacts whose company name contains any of these values, ignoring case. Contacts with no company stay.
companyDomainContainsstringoptionalKeeps contacts whose company domain contains this text, ignoring case.
companyDescriptionContainsstringoptionalKeeps contacts whose company description contains this text, ignoring case.
companySpecialitiesContainsstringoptionalKeeps contacts whose company specialities contain this text, ignoring case.
industriesarray of stringoptionalKeeps contacts whose company industry is one of these values, ignoring case. industries in GET /v1/segments/filter-options lists common values.
excludeIndustriesarray of stringoptionalDrops contacts whose company industry is one of these values, ignoring case. Contacts with no industry stay.
companyHeadcountIntRangeoptionalThe company's number of employees. Contacts with no company do not match a bound.
companyFollowersIntRangeoptionalThe company's number of followers. Contacts with no company do not match a bound.
companyFoundedYearIntRangeoptionalThe year the company was founded, each bound from 0 to 32767. Contacts with no company do not match a bound.
companyTypesarray of stringoptionalKeeps contacts whose company type is exactly one of these values. companyTypes in GET /v1/segments/filter-options lists the values.
lastFundingRoundsarray of stringoptionalKeeps contacts whose company's last funding round contains any of these values, ignoring case. lastFundingRounds in GET /v1/segments/filter-options lists the values.
totalFundingLongRangeoptionalThe company's total funding. Contacts with no company do not match a bound.
technologiesarray of stringoptionalKeeps contacts whose company uses any of these technologies. A value must match one whole entry of the company's technology list.
excludeTechnologiesarray of stringoptionalDrops contacts whose company uses any of these technologies, matched the same way as technologies. Contacts with no company or technology list stay.
companyHqCountriesarray of stringoptionalKeeps contacts whose company headquarters country is exactly one of these values.
excludeCompanyHqCountriesarray of stringoptionalDrops contacts whose company headquarters country is exactly one of these values. Contacts with no company or headquarters country stay.
companyHqStatestringoptionalKeeps contacts whose company headquarters state or region contains this text, ignoring case.
companyHqCitystringoptionalKeeps contacts whose company headquarters city contains this text, ignoring case.
doNotContactbooleanoptionalTrue keeps only contacts marked do not contact, and false keeps only the others.
createdAtDateRangeoptionalWhen the contact was added.
totalClicksIntRangeoptionalThe number of email link clicks the contact made, summed across all campaigns. A contact with no clicks counts as 0.
leadQualityScoreIntRangeoptionalThe lead quality score Ken gave the contact in its campaign, each bound from 1 to 10. Contacts without a score do not match.
behaviorTagsarray of stringoptionalKeeps 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.
behaviorTagsExcludearray of stringoptionalDrops contacts that carry any of these behavior tags. Needs the behavior signals feature, with the same tag rules as behaviorTags.
aiVariableFiltersarray of AiVariableFilteroptionalRules 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.
customVariableFiltersarray of CustomVariableFilteroptionalRules 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.
Request
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

POST/v1/segments/{segmentId}/activatesegments.activate
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

POST/v1/segments/{segmentId}/deactivatesegments.deactivate
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

GET/v1/segments/filter-optionssegments.get-filter-options
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

GET/v1/segments/{segmentId}/provider-trackssegments.get-provider-tracks
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 code feature_disabled).
  • 404 not_found: the segment does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
segmentIdpathinteger (int64)requiredId of the segment.
Request
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

PUT/v1/segments/{segmentId}/provider-tracks/{track}segments.set-provider-track
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 code feature_disabled (the workspace does not have provider tracks), invalid_track, invalid_sequence, no_sequence (the segment has no email sequence to copy) or sequence_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

NameInTypeRequiredDescription
segmentIdpathinteger (int64)requiredId of the segment.
trackpathstringrequiredThe provider track: google, microsoft or other.

Request body

application/json, optional.

The sequence the track sends: own or shared.

FieldTypeRequiredDescription
sequencestringoptionalown gives the track its own copy of the segment's sequence; shared drops that copy.
Request
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

POST/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

Try it on developer.ken.so

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 code feature_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

NameInTypeRequiredDescription
segmentIdpathinteger (int64)requiredId of the segment.
trackpathstringrequiredThe provider track whose copy all tracks get: google, microsoft or other.
Request
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

GET/v1/segments/{segmentId}/versionssegments.list-versions
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is out of range, or cursor is invalid.
  • 404 not_found: the segment does not exist in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalVersions per page, from 1 to 100. Defaults to 20.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

POST/v1/segments/{segmentId}/versionssegments.save-version
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 of PATCH /v1/segments/{segmentId}.
  • 400 validation_failed: sourceVersionId is 0.
  • 404 not_found: the segment does not exist in this workspace, or sourceVersionId is 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.

FieldTypeRequiredDescription
sourceVersionIdinteger (int64)optionalThe 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.
namestringoptionalA new name, unique within the campaign. Cannot be empty.
descriptionstringoptionalA new description. Null clears it.
segmentationTypestringoptionalmanual, ai or ab_test. A segment with filters can change only to manual.
abTestPercentageinteger (int32)optionalThe 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.
sortOrderinteger (int32)optionalThe segment's display position among the campaign's segments.
filterCriteriaCampaignSegmentFilterCriteriaoptionalReplaces 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.
Request
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

GET/v1/segments/{segmentId}/versions/{versionId}segments.get-version
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
versionIdpathinteger (int64)requiredThe version's id, from the list of versions.
Request
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

POST/v1/segments/{segmentId}/versions/{versionId}/restoresegments.restore-version
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 conflict with error.impact: the restore would clear AI output and confirm is not true.
  • 409 conflict: another version save for this segment is running. Retry shortly.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
versionIdpathinteger (int64)requiredThe id of the version to restore.

Request body

application/json, optional.

FieldTypeRequiredDescription
confirmbooleanoptionalSet 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.
dryRunbooleanoptionalSet to true to see what the restore would do without changing anything. Defaults to false.
Request
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.


On this page