> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/segments/openapi.json](/docs/api/segments/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Segments: Preview a segment filter

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Segments](/docs/api/segments.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Preview a segment filter

`POST /v1/campaigns/{campaignId}/segments/preview` - operationId `segments.preview`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 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 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.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/segments/POST/v1/campaigns/%7BcampaignId%7D/segments/preview)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | The campaign's id. |
| `segmentId` | query | integer (int64) | no | 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. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fullName` | StringFilter | no | Matches the contact's full name. |
| `titles` | array of string | no | Keeps contacts whose job title contains any of these values, ignoring case. |
| `excludeTitles` | array of string | no | Drops contacts whose job title contains any of these values, ignoring case. Contacts with no title stay. |
| `lastJobTitle` | StringFilter | no | Matches the contact's last job title. |
| `headlines` | array of string | no | Keeps contacts whose headline contains any of these values, ignoring case. |
| `excludeHeadlines` | array of string | no | Drops contacts whose headline contains any of these values, ignoring case. Contacts with no headline stay. |
| `summaryContains` | string | no | Keeps contacts whose profile summary contains this text, ignoring case. |
| `seniorityLevels` | array of string | no | 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 | no | Drops contacts whose seniority level is exactly one of these values. Contacts with no seniority level stay. |
| `functions` | array of string | no | 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 | no | Drops contacts whose job function is exactly one of these values. Contacts with no function stay. |
| `employmentTypes` | array of string | no | Keeps contacts whose employment type is exactly one of these values. `employmentTypes` in `GET /v1/segments/filter-options` lists the values. |
| `isDecisionMaker` | boolean | no | True keeps only contacts marked as decision makers, and false keeps only the others. |
| `changedJobRecently` | boolean | no | True keeps only contacts marked as having changed jobs recently, and false keeps only the others. |
| `yearsOfExperience` | FloatRange | no | The contact's total years of work experience. Contacts with no value do not match a bound. |
| `yearsInCurrentRole` | FloatRange | no | The contact's years in their current role. Contacts with no value do not match a bound. |
| `yearsInCurrentCompany` | FloatRange | no | The contact's years at their current company. Contacts with no value do not match a bound. |
| `profileCountries` | array of string | no | Keeps contacts whose country is exactly one of these values. |
| `excludeProfileCountries` | array of string | no | Drops contacts whose country is exactly one of these values. Contacts with no country stay. |
| `profileState` | string | no | Keeps contacts whose state or region contains this text, ignoring case. |
| `profileCity` | string | no | Keeps contacts whose city contains this text, ignoring case. |
| `skillsContains` | string | no | Keeps contacts whose skills contain this text, ignoring case. |
| `certificationsContains` | string | no | Keeps contacts whose certifications contain this text, ignoring case. |
| `languages` | array of string | no | Keeps contacts whose languages contain any of these values, ignoring case, such as `French`. |
| `emailValidity` | array of string | no | 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 | no | 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 | no | 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 | no | 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 | no | True keeps only contacts with a LinkedIn profile URL, and false keeps only contacts without one. |
| `hasPhone` | boolean | no | True keeps only contacts with a phone number, and false keeps only contacts without one. |
| `hasValidPhone` | boolean | no | 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 | no | Keeps contacts whose company name contains any of these values, ignoring case. |
| `excludeCompanyNames` | array of string | no | Drops contacts whose company name contains any of these values, ignoring case. Contacts with no company stay. |
| `companyDomainContains` | string | no | Keeps contacts whose company domain contains this text, ignoring case. |
| `companyDescriptionContains` | string | no | Keeps contacts whose company description contains this text, ignoring case. |
| `companySpecialitiesContains` | string | no | Keeps contacts whose company specialities contain this text, ignoring case. |
| `industries` | array of string | no | 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 | no | Drops contacts whose company industry is one of these values, ignoring case. Contacts with no industry stay. |
| `companyHeadcount` | IntRange | no | The company's number of employees. Contacts with no company do not match a bound. |
| `companyFollowers` | IntRange | no | The company's number of followers. Contacts with no company do not match a bound. |
| `companyFoundedYear` | IntRange | no | 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 | no | 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 | no | 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 | no | The company's total funding. Contacts with no company do not match a bound. |
| `technologies` | array of string | no | 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 | no | 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 | no | Keeps contacts whose company headquarters country is exactly one of these values. |
| `excludeCompanyHqCountries` | array of string | no | Drops contacts whose company headquarters country is exactly one of these values. Contacts with no company or headquarters country stay. |
| `companyHqState` | string | no | Keeps contacts whose company headquarters state or region contains this text, ignoring case. |
| `companyHqCity` | string | no | Keeps contacts whose company headquarters city contains this text, ignoring case. |
| `doNotContact` | boolean | no | True keeps only contacts marked do not contact, and false keeps only the others. |
| `createdAt` | DateRange | no | When the contact was added. |
| `totalClicks` | IntRange | no | The number of email link clicks the contact made, summed across all campaigns. A contact with no clicks counts as 0. |
| `leadQualityScore` | IntRange | no | 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 | no | 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 | no | 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 | no | 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 | no | 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. |

### Response 200

`data` is a `SegmentPreview`.

| Field | Type | Description |
| --- | --- | --- |
| `matchingCount` | integer (int32) | The number of contacts that match the filter. 0 when you sent no body. |
| `totalCampaignContacts` | integer (int32) | The number of contacts the preview looked at: contacts with no segment, contacts in the Default segment, and the contacts of `segmentId` when you passed it. Contacts on the do-not-contact list count only when the filter sets `doNotContact` to true. 0 when you sent no body. |
| `sampleContacts` | array of SegmentPreviewContact | Up to 10 matching contacts, newest first. Empty when you sent no body. |
| `filterOptions` | SegmentFilterMetadata | The values to offer for the list filters, the same as `GET /v1/segments/filter-options` returns. |

### Request

```bash
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
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "matchingCount": 640,
    "totalCampaignContacts": 1840,
    "sampleContacts": [
      {
        "id": 90125,
        "fullName": "Amanda Chen",
        "title": "VP of Engineering",
        "companyName": "Northwind Labs",
        "location": "Austin, Texas, United States",
        "email": "amanda.chen@northwind.example.com",
        "emailValidity": "safe"
      }
    ],
    "filterOptions": {
      "seniorityLevels": [
        {
          "value": "Director",
          "label": "Director"
        },
        {
          "value": "VP",
          "label": "VP"
        },
        {
          "value": "CLevel",
          "label": "C-Level"
        }
      ],
      "functions": [
        {
          "value": "Engineering",
          "label": "Engineering"
        },
        {
          "value": "Product Management",
          "label": "Product Management"
        },
        {
          "value": "Sales",
          "label": "Sales"
        }
      ],
      "industries": [
        {
          "value": "Computer Software",
          "label": "Computer Software"
        },
        {
          "value": "Financial Services",
          "label": "Financial Services"
        },
        {
          "value": "Internet",
          "label": "Internet"
        }
      ],
      "companyTypes": [
        {
          "value": "Privately Held",
          "label": "Privately Held"
        },
        {
          "value": "Public Company",
          "label": "Public Company"
        }
      ],
      "employmentTypes": [
        {
          "value": "Full-time",
          "label": "Full-time"
        },
        {
          "value": "Contract",
          "label": "Contract"
        }
      ],
      "lastFundingRounds": [
        {
          "value": "Seed",
          "label": "Seed"
        },
        {
          "value": "Series A",
          "label": "Series A"
        },
        {
          "value": "Series B",
          "label": "Series B"
        }
      ],
      "technologies": [],
      "emailValidity": [
        {
          "value": "Safe",
          "label": "Valid (Safe)"
        },
        {
          "value": "Verified",
          "label": "Verified"
        },
        {
          "value": "CatchAll",
          "label": "Catch-All"
        }
      ],
      "emailProviders": [
        {
          "value": "Prospeo",
          "label": "Prospeo"
        },
        {
          "value": "KenFinder",
          "label": "Found by Kenso"
        }
      ],
      "languages": [
        {
          "value": "English",
          "label": "English"
        },
        {
          "value": "Spanish",
          "label": "Spanish"
        },
        {
          "value": "German",
          "label": "German"
        }
      ]
    }
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### StringFilter

A text match on one contact field, ignoring case. A contact without a value in the field never matches `contains` and always passes `notContains`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contains` | string | no | Keeps contacts whose field contains this text. At most 500 characters. Null or omitted skips it. |
| `notContains` | string | no | Drops contacts whose field contains this text. At most 500 characters. Null or omitted skips it. |

### FloatRange

A range of numbers that can have decimals. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | number (float) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | number (float) | no | The highest value that matches. Null or omitted sets no upper bound. |

### IntRange

A range of whole numbers. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | integer (int32) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | integer (int32) | no | The highest value that matches. Null or omitted sets no upper bound. |

### LongRange

A range of whole numbers that can be large. Both bounds are inclusive, and a null or omitted bound leaves that side open. `min` cannot be greater than `max`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `min` | integer (int64) | no | The lowest value that matches. Null or omitted sets no lower bound. |
| `max` | integer (int64) | no | The highest value that matches. Null or omitted sets no upper bound. |

### DateRange

A range of dates and times. Both ends are inclusive, and a null or omitted end leaves that side open. `from` cannot be later than `to`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string (date-time) | no | The earliest date and time that matches, in ISO 8601. Null or omitted sets no start. |
| `to` | string (date-time) | no | The latest date and time that matches, in ISO 8601. Null or omitted sets no end. |

### AiVariableFilter

A rule on the output of one of the campaign's AI prompts.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `promptId` | integer (int64) | no | The id of the AI prompt whose output the rule checks. |
| `operator` | string, one of: exists, not_exists, contains, not_contains | no | How the rule matches, such as `contains`. Kenso also reads the PascalCase name (`Contains`). |
| `value` | string | no | The text to look for with `contains` and `not_contains`, at most 500 characters. Kenso ignores it for `exists` and `not_exists`. |

### CustomVariableFilter

A rule on one of the contact's campaign custom variables.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `variableKey` | string | no | The custom variable to check, such as `deal_stage`, at most 500 characters. Kenso normalizes the key the same way as custom variable names, so `Deal Stage` checks `deal_stage`. |
| `operator` | string, one of: contains, not_contains, equals, not_equals, is_empty, is_not_empty | no | How the rule matches, such as `equals`. Kenso also reads the PascalCase name (`Equals`). |
| `value` | string | no | The text to compare, at most 500 characters. Required for `contains`, `not_contains`, `equals` and `not_equals`. Kenso ignores it for `is_empty` and `is_not_empty`. |

### SegmentPreviewContact

A contact that matches a previewed segment filter.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The contact's id. |
| `fullName` | string | no | The contact's full name. Null when unknown. |
| `title` | string | no | The contact's job title. Null when unknown. |
| `companyName` | string | no | The name of the contact's company. Null when unknown. |
| `location` | string | no | The contact's location as free text. Null when unknown. |
| `email` | string | no | One of the contact's email addresses. Null when the contact has none. |
| `emailValidity` | string | no | The verification result for `email`: `safe`, `verified`, `catch_all`, `risky`, `invalid` or `unknown`. Null when the contact has no email address. |

### SegmentFilterMetadata

The values to offer for the list filters of a segment. Each list holds the options for the filter field of the same name.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seniorityLevels` | array of FilterOptionItem | no | Options for `seniorityLevels` and `excludeSeniorityLevels`. |
| `functions` | array of FilterOptionItem | no | Options for `functions` and `excludeFunctions`. |
| `industries` | array of FilterOptionItem | no | Common options for `industries` and `excludeIndustries`. Those filters also accept other industries. |
| `companyTypes` | array of FilterOptionItem | no | Options for `companyTypes`. |
| `employmentTypes` | array of FilterOptionItem | no | Options for `employmentTypes`. |
| `lastFundingRounds` | array of FilterOptionItem | no | Options for `lastFundingRounds`. |
| `technologies` | array of FilterOptionItem | no | Options for `technologies` and `excludeTechnologies`. Empty: those filters take any technology name. |
| `emailValidity` | array of FilterOptionItem | no | Options for `emailValidity`, the verification result of an email address. |
| `emailProviders` | array of FilterOptionItem | no | Options for `emailProviders` and `excludeEmailProviders`, the source that found an email address. |
| `languages` | array of FilterOptionItem | no | Common options for `languages`. The filter also accepts other languages. |

### FilterOptionItem

One value a segment filter field accepts, with a label to show.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | no | The value to send in the filter field. |
| `label` | string | no | A label to show for the value. |
| `category` | string | no | A group the option belongs to. Null when the option has no group. |
