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

# Triggers: Preview a trigger's matching companies

> **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 [Triggers](/docs/api/triggers.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Preview a trigger's matching companies

`POST /v1/triggers/preview` - operationId `triggers.preview`

| Permission | Rate limit |
| --- | --- |
| Campaigns edit | 240 requests a minute per API key |

Runs a trigger's parameters against live company data and shows which companies would match, how many pass
each step, and an estimated credit cost. Kenso saves nothing, fires nothing and charges nothing, and the
preview does not use your export allowance. Use it to tune parameters before you create the trigger.

`signalType` is `fundraising`, `open_roles` or `company_headcount_growth`.
`parameters` is a JSON object with the same keys a trigger stores. `limit` is from 1 to 25 companies,
default 25. To read the next page, pass `pagination.nextCursor` as `cursor`.

Every page has:

- `companies`: sample matching companies.
- `total`: the matching companies across all pages, or null for `open_roles`.
- `steps`: the name, count and description of each filter step on this page, in order. The last step,
`max_contacts_per_company`, is the most people the page can import.
- `estimatedCredits`: `isEstimate` (always true), `leads`, `credits`,
`totalMillicredits`, `lines` and `basis`. `basis` says how Kenso computed it: those people
at the leads rate of `POST /v1/credits/estimates`.

Errors:

- `400 validation_failed`: `signalType` or `parameters` is invalid. For a signal type the
preview does not cover, `error.details[0].code` is `preview_not_supported`.

Requires Campaigns edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/triggers/POST/v1/triggers/preview)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 |
| --- | --- | --- | --- |
| `signalType` | string | yes | Required. The signal type to preview: `fundraising`, `open_roles` or `company_headcount_growth`. |
| `parameters` | object | yes | Required. The trigger's parameters as a JSON object, with the same keys a trigger stores. |
| `limit` | integer (int32) | no | How many companies to return, from 1 to 25. Default 25. |
| `cursor` | string | no | The `pagination.nextCursor` of the previous page. |

### Response 200

`data` is a `TriggerPreviewPage`.

| Field | Type | Description |
| --- | --- | --- |
| `signalType` | string | The previewed signal type: `open_roles` or `company_headcount_growth`. Left out for `fundraising`. |
| `month` | string | The month of the headcount data, as `yyyy-MM`. Present only for `company_headcount_growth`. |
| `companies` | array of TriggerPreviewCompany | Sample matching companies on this page. |
| `total` | integer (int64) | The matching companies across all pages. Null for `open_roles`. For `fundraising` it stops at 1,000 (see `totalIsCapped`). |
| `totalIsCapped` | boolean | True when `total` stopped at 1,000, so more companies match. Present only for `fundraising`. |
| `steps` | array of TriggerPreviewStep | Each filter step on this page, in order, with how many companies or people pass it. The last step, `max_contacts_per_company`, is the most people the page can import. |
| `estimatedCredits` | TriggerPreviewCreditEstimate | The estimated lead credits for the people this page can import. Kenso charges nothing for a preview. |
| `pagination` | TriggerPreviewPagination | How to get the next page. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/triggers/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 '{
  "signalType": "fundraising",
  "parameters": null,
  "limit": 1,
  "cursor": "eyJpZCI6ODE1fQ"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "signalType": "open_roles",
    "month": "string",
    "companies": [
      {
        "kenCompanyId": 812,
        "companyId": 812,
        "name": "string",
        "domain": "acme.com",
        "linkedinUrl": "https://example.com",
        "openJobCount": 1,
        "jobs": [
          {
            "title": "string",
            "location": "string",
            "source": "string",
            "url": "https://example.com"
          }
        ],
        "previousHeadcount": 1,
        "currentHeadcount": 1,
        "growthAbs": 1,
        "growthPct": 0.5,
        "websiteUrl": "https://example.com",
        "city": "string",
        "state": "string",
        "industry": "string",
        "revenueRange": "string",
        "foundedYear": 1,
        "totalRaisedUsd": 1,
        "raises": [
          {
            "reportedAt": "string",
            "amountRaisedUsd": 1,
            "roundRaisedUsd": 1,
            "roundSizeUsd": 1,
            "isOpenEnded": true,
            "investorCount": 1,
            "isNewRound": true
          }
        ],
        "executives": [
          {
            "name": "string",
            "title": "string"
          }
        ]
      }
    ],
    "total": 1,
    "totalIsCapped": true,
    "steps": [
      {
        "name": "string",
        "count": 1,
        "description": "string"
      }
    ],
    "estimatedCredits": {
      "isEstimate": true,
      "leads": 1,
      "totalMillicredits": 1,
      "credits": 0.5,
      "lines": [
        {
          "action": "ai_qualification",
          "units": 1,
          "millicredits": 1,
          "description": "string"
        }
      ],
      "basis": "string"
    },
    "pagination": {
      "nextCursor": "eyJpZCI6ODE1fQ",
      "hasMore": true
    }
  }
}
```

## Types

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

### TriggerPreviewCompany

A sample company on a trigger preview page. The fields present depend on the signal type. Kenso may add fields to it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kenCompanyId` | integer (int64) | no | The company's Kenso company id. Present for `open_roles` and `company_headcount_growth`. |
| `companyId` | integer (int64) | no | The company's id in the funding data, the value the funding round `companyIds` filter takes. Present only for `fundraising`. |
| `name` | string | no | The company's name. Null when unknown. |
| `domain` | string | no | The company's web domain, for example `acme.com`. Null when unknown. |
| `linkedinUrl` | string | no | The company's LinkedIn page URL. Null when unknown. Present for `open_roles` and `company_headcount_growth`. |
| `openJobCount` | integer (int32) | no | How many open jobs the company has. Present only for `open_roles`. |
| `jobs` | array of TriggerPreviewJob | no | Up to 3 of the company's matching open jobs. Present only for `open_roles`. |
| `previousHeadcount` | integer (int32) | no | The company's employee count the month before. Null when unknown. Present only for `company_headcount_growth`. |
| `currentHeadcount` | integer (int32) | no | The company's employee count this month. Null when unknown. Present only for `company_headcount_growth`. |
| `growthAbs` | integer (int32) | no | How many employees the company added over the month. Null when unknown. Present only for `company_headcount_growth`. |
| `growthPct` | number (float) | no | The company's headcount growth over the month, in percent. Null when unknown. Present only for `company_headcount_growth`. |
| `websiteUrl` | string | no | The company's website URL. Null when unknown. Present only for `fundraising`. |
| `city` | string | no | The city the company reported with its newest matching round. Null when unknown. Present only for `fundraising`. |
| `state` | string | no | The two-letter US state the company reported. Null outside the US or when unknown. Present only for `fundraising`. |
| `industry` | string | no | The company's industry as reported with its newest matching round. Null when unknown. Present only for `fundraising`. |
| `revenueRange` | string | no | The company's revenue range as reported with its newest matching round. Null when unknown. Present only for `fundraising`. |
| `foundedYear` | integer (int32) | no | The year the company was founded. Null when unknown. Present only for `fundraising`. |
| `totalRaisedUsd` | integer (int64) | no | The company's total raised to date across all its rounds, in whole US dollars. Null when unknown. Present only for `fundraising`. |
| `raises` | array of TriggerPreviewRaise | no | Up to 10 of the company's matching round reports, newest first. Present only for `fundraising`. |
| `executives` | array of TriggerPreviewExecutive | no | The executive officers named on the newest matching round. Present only for `fundraising`. |

### TriggerPreviewStep

One filter step of a trigger preview.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The step: `funding_filters` for `fundraising`; `job_filter`, `resolved_company` for `open_roles`; `min_growth_pct`, `min_growth_abs` for `company_headcount_growth`; `min_company_size` and `people_filter` for both of those; and `max_contacts_per_company`, always last. |
| `count` | integer (int64) | no | How many companies on this page pass the step, or people for `people_filter` and `max_contacts_per_company`. Null when the step could not be counted. |
| `description` | string | no | What the step counts, in words. |

### TriggerPreviewCreditEstimate

An estimate of the lead credits for the people a preview page can import. Never charged.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isEstimate` | boolean | no | Always true: this is an estimate, not a quote. |
| `leads` | integer (int32) | no | The people the page can import, the count of the `max_contacts_per_company` step. |
| `totalMillicredits` | integer (int64) | no | The estimated cost in millicredits (1,000 to a credit). |
| `credits` | number (double) | no | The estimated cost in credits. |
| `lines` | array of TriggerPreviewCreditLine | no | The estimate per charged action. Empty when `leads` is 0. |
| `basis` | string | no | How Kenso computed the estimate, in words. |

### TriggerPreviewPagination

How to get the next page of a trigger preview. Kenso may add fields to it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `nextCursor` | string | no | Send it as `cursor` with the same parameters to get the next page. Null on the last page. |
| `hasMore` | boolean | no | True when there is a next page. Left out for `fundraising`; read `nextCursor` there. |

### TriggerPreviewJob

A sample open job of a company on an `open_roles` preview.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no | The job title. Null when unknown. |
| `location` | string | no | The job's location. Null when unknown. |
| `source` | string | no | The job board the posting came from. Null when unknown. |
| `url` | string | no | The URL to apply for the job. Null when unknown. |

### TriggerPreviewRaise

A report of a round on a `fundraising` preview. Kenso may add fields to it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reportedAt` | string | no | The day the round was reported, as `yyyy-MM-dd`. |
| `amountRaisedUsd` | integer (int64) | no | The money this report adds, in whole US dollars. Null when unknown. |
| `roundRaisedUsd` | integer (int64) | no | The total sold in the round so far, in whole US dollars. Null when unknown. |
| `roundSizeUsd` | integer (int64) | no | The round's target size in whole US dollars. Null when the round is open-ended or the size is unknown. |
| `isOpenEnded` | boolean | no | True when the round has no set size. |
| `investorCount` | integer (int32) | no | How many investors have put money into the round. Null when unknown. |
| `isNewRound` | boolean | no | True when this is the first report of a new round, false for a later update of a round. |

### TriggerPreviewExecutive

An executive officer named on a round. Kenso may add fields to it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The person's full name. Null when unknown. |
| `title` | string | no | The person's title as reported, or `Executive officer` when none is given. |

### TriggerPreviewCreditLine

One charged action in a trigger preview's credit estimate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | no | The action: `ai_qualification`, `email_found` or `ai_personalization`. |
| `units` | integer (int64) | no | How many times the action runs. |
| `millicredits` | integer (int64) | no | The estimated cost of the action in millicredits. |
| `description` | string | no | What the action covers, in words. |
