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

# Campaigns: Get a campaign

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

## Get a campaign

`GET /v1/campaigns/{campaignId}` - operationId `campaigns.get`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Returns one campaign with its settings, sending progress and, while it is paused, why. `leadCount` is
counted live. `readyLeadCount` is counted live too, for up to 2 seconds, then the last stored count.

Errors:

- `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/campaigns/GET/v1/campaigns/%7BcampaignId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | path | integer (int64) | yes | Id of the campaign. |
| `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`. |

### Response 200

`data` is a `Campaign`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | Id of the campaign. |
| `name` | string | Display name of the campaign. |
| `status` | string | Where the campaign stands: `draft`, `building`, `ready`, `active` (sending or launching), `paused`, `completed`, `error` or `archived`. A campaign that is both building and ready shows `ready`. |
| `channel` | string | Always `email` for now. |
| `contactLimit` | integer (int32) | The campaign's contact limit. With `contactLimitPeriod` `month` it is the new qualified contacts with a Safe email the campaign may add per UTC calendar month; with `total` it is a lifetime total. |
| `contactLimitPeriod` | string | What `contactLimit` counts: `month` or `total`. |
| `contactLimitUsed` | integer (int32) | Contacts counted against `contactLimit`: this month's for a monthly limit, else `contactCount`. |
| `contactLimitResetsAt` | string (date-time) | When a monthly count starts again (UTC), the next 1st at 00:00. Omitted for a total limit. |
| `fairUseContactLimit` | integer (int32) | The lifetime fair-use ceiling that applies on top of a monthly limit. Omitted for a total limit. |
| `contactLimitReached` | boolean | True while Kenso stops adding contacts because the campaign hit its contact limit, the fair-use ceiling or the workspace ran out of lead credits. |
| `contactLimitReachedReason` | string | Why `contactLimitReached` is true: `monthly_limit`, `contact_limit`, `fair_use` or `lead_credits`. Omitted when it is false. |
| `contactCount` | integer (int32) | Contacts in the campaign with a valid email. `leadCount` counts every contact. |
| `leadCount` | integer (int32) | Every contact in the campaign, with or without an email, so a LinkedIn-only campaign shows its contacts. Single-campaign responses count it live. On `GET /v1/campaigns` it comes from a cached count that usually trails by under 15 minutes. Omitted when the count cannot be read or does not finish within 1 second on a very large workspace. |
| `readyLeadCount` | integer (int32) | Ready leads still waiting for their first email: leads that pass the sequencer's ready checks (qualified when the campaign qualifies, a Safe or Verified email, every variable the sequence uses filled, an active segment, not blocklisted), have no email sent or queued, and whose sequence has not stopped (for example after a reply, a hard bounce or an unsubscribe). `POST /v1/contacts/search` with `awaitingFirstEmail` lists the same leads. Single-campaign responses count it live, waiting up to 2 seconds before they return the last stored count. On `GET /v1/campaigns` it is the stored count: a list recounts the counts of launched campaigns older than 10 minutes in the background, so it can trail, and a campaign with no stored count yet omits it. Omitted when it cannot be read. |
| `linkedInOnly` | boolean | True for a LinkedIn-only campaign: a batch campaign whose LinkedIn settings say LinkedIn only, with an active LinkedIn step and no usable email step. Returned only on `GET /v1/campaigns` items, and omitted when it cannot be read. |
| `segmentCount` | integer (int32) | Number of segments in the campaign. Omitted when it was not read. |
| `inboxCount` | integer (int32) | Number of inboxes the campaign sends from: the inboxes `GET /v1/campaigns/{campaignId}/inboxes` lists, 0 when it has none. Omitted when it could not be read. |
| `tagIds` | array of integer (int64) | Ids of the tags on the campaign, ascending: the tags `GET /v1/tags` lists that are assigned to it, empty when it has none. Returned only on `GET /v1/campaigns` items, with `includeTagIds=true`. |
| `createdAt` | string (date-time) | When the campaign was created (UTC). |
| `launchedAt` | string (date-time) | When the campaign first launched (UTC). Omitted until it launches. |
| `sourceStatus` | string | Where contact sourcing for the campaign stands: `draft`, `to_scrape`, `in_progress`, `scraped`, `done` or `error`. `status` is the overall state. |
| `sendingStatus` | string | Where sending stands: `not_started`, `scheduled`, `launching`, `sending`, `paused`, `completed`, `error` or `archived`. `status` is `active` while this is `sending` or `launching`. |
| `processingStatus` | array of string | The processing steps running or done, as a list: `draft`, `to_do`, `uploading`, `importing`, `scraping`, `qualifying`, `enriching_data`, `finding_emails`, `verifying_emails`, `segmenting`, `personalizing`, `rewriting`, `generating_links`, `ready`, `finished`, `done`, `paused` or `error`. `["none"]` when nothing is set. |
| `sendingDays` | array of integer (int32) | Days the campaign sends on, sorted: 0 (Sunday) to 6 (Saturday). Omitted when none are set. |
| `sendingStartTime` | string | Start of the daily sending window, such as `09:00`, in `sendingTimezone`. Omitted when not set. |
| `sendingEndTime` | string | End of the daily sending window, such as `17:00`, in `sendingTimezone`. Omitted when not set. |
| `sendingTimezone` | string | Time zone of the sending window: a supported IANA name such as `America/New_York`, or `prospect` to send in each contact's own time zone. Omitted when not set. |
| `maxEmailsPerDay` | integer (int32) | Most emails the campaign sends per day across its inboxes. Omitted when not set. |
| `sendingError` | string | The current sending problem, as text: the kind of failure, how many sends failed recently, and the inboxes involved. Set while hard send failures stay above the alert rate, and cleared once they drop. Omitted when there is none. |
| `sendingErrorAt` | string (date-time) | When the current `sendingError` began (UTC). Omitted with it. |
| `ownerMemberId` | integer (int64) | Member id of the campaign owner: the owner set on the campaign, else the member who created it while they are still in the workspace. Omitted when neither applies. |
| `stopOnReply` | boolean | A contact's reply stops their sequence. When false, neutral and positive replies let it continue, and a negative reply, an unsubscribe or a booked meeting still stops it. This and the other sending switches (`trackClicks`, `unsubscribeLink`) take effect only when the workspace has the campaign send settings feature; the field shows the saved value either way. `trackOpens` is always false. |
| `stopCompanyOnReply` | boolean | A reply also stops every other contact at the same company. It is the same setting as `stopSequenceForCompanyOnReply` in the LinkedIn settings. New sales campaigns start with it on and a duplicate keeps its source's value. False when the campaign has no LinkedIn settings. |
| `groupSameCompanySends` | boolean | Contacts at the same company get their emails on the same day. New sales campaigns start with it on. |
| `newLeadsFirst` | boolean | First emails take the campaign's daily capacity ahead of follow-ups, so every contact gets email 1 before older contacts get their next step. False (the default) sends due follow-ups first. On a campaign that keeps getting new contacts, follow-ups can wait as long as it stays on, so turn it off once `awaitingFirstEmailCount` reaches 0. Duplicates, templates saved from the campaign and drafts made from those templates start with it off. |
| `catchAllLaneEnabled` | boolean | The campaign opts in to the catch-all lane: Kenso may also send to unverified catch-all addresses whose catch-all score is high enough, from the workspace's own inboxes, with a daily cap per campaign and per inbox. The lane pauses itself when too many of its sends bounce (`catchAllLanePausedAt`). False (the default) never sends to a catch-all address. It has no effect until Kenso turns the lane on for all workspaces, and copies of the campaign start with it off. |
| `emailVerifiers` | array of string | The verifiers that check the campaign's emails: Kenso's (`kenso`, its own mailbox check, `leadmagic`, LeadMagic catch-all, and `findymail`) run first, in the order Kenso picks, then `zerobounce`, then `neverbounce`, which run on the workspace's own ZeroBounce or NeverBounce key and spend its credits, never Kenso's. Each is asked only for the emails the ones before it left undecided. An empty list means the campaign verifies no email; a PATCH names at least one. Returned on single-campaign responses only. |
| `catchAllLanePausedAt` | string (date-time) | When the catch-all lane paused itself because too many of its sends hard-bounced (UTC). Kenso sets and clears it; you cannot write it. Omitted while the lane is not paused. |
| `sourceLanguage` | string | Language the steps are written in: a market locale such as `fr-FR`, or a bare language such as `en` (the default). Changing this or any other language setting needs the multilingual outreach feature. |
| `languageMode` | string | How the campaign picks the language of each email: `source_only` (the default) sends every contact the source text, and `auto` sends a contact the approved translation for their language when `enabledLanguages` lists it. |
| `enabledLanguages` | array of string | Market locales the campaign translates into, such as `fr-FR` and `es-MX`. Empty when none. |
| `formalityOverrides` | map of string | Tone per locale, `formal` or `informal`, overriding the locale's default. Empty when every locale uses its default. |
| `languageFallback` | string | What an `auto` campaign does for a contact whose language has no approved translation: `source` (the default) sends the source text, `hold` holds the contact until a translation is approved. |
| `awaitingFirstEmailCount` | integer (int32) | Ready contacts still waiting for their first email. Not counted: contacts in a paused segment or held back by the ready checks, company Cc members, contacts paused in bulk, and contacts whose sequence already stopped (for example after a company reply, a hard bounce or an unsubscribe). Contacts waiting for batch approval, held by an account play, or live in another campaign are counted, so the number can stop falling above 0 while they wait. Returned on single-campaign responses while `newLeadsFirst` is true; omitted otherwise, on the list, and when it cannot be read. It is the same count as `readyLeadCount`. |
| `rampUpDays` | integer (int32) | Ramp-up length in scheduled sending days, from 0 (no ramp) to 30. Daily volume grows over these days. New campaigns start at 5. |
| `trackClicks` | boolean | Links in emails go through tracking links. See `stopOnReply` for when this switch applies. |
| `trackOpens` | boolean | Always false: campaign emails never carry an open-tracking pixel. Opens are not tracked and are never reported. |
| `unsubscribeLink` | boolean | Emails carry the `List-Unsubscribe` headers. When false, the headers are left out only of steps whose body has the `{{unsubscribe_link}}` link, so every email still has a way to opt out. See `stopOnReply` for when this switch applies. |
| `sendAsPlainText` | boolean | Emails written as HTML go out as plain text only (`text/plain`, no HTML part). Off by default; Kenso can turn it off for every campaign at once, so a campaign with it on may still send HTML. Steps with a drawn handwritten letter, a video, a Studio email, a provider-built message or any image in the sent body (a signature logo counts) keep their HTML. Unlike `stopOnReply` and the other sending switches, changing it needs no feature. |
| `protectAccountPlays` | boolean | Skip people in active account plays (stage `warming`, `engaged`, `meeting_booked` or `in_deal`). New campaigns start with it on. It applies only when the workspace has account plays. |
| `bookingMeetingTypeId` | integer (int64) | Id of the round robin meeting type that takes this campaign's bookings when the contact's account owner and the sender cannot. Omitted when none is set. |
| `replyTo` | string | This campaign's Reply-To address, used instead of the workspace's. It is a connected inbox of the workspace, and emails sent from that same inbox carry no Reply-To. Omitted when the campaign uses the workspace's setting. |
| `excludedCountries` | array of string | Countries this campaign never sends to, as upper-case ISO 3166-1 alpha-2 codes, sorted. Imports drop a contact from a listed country, and Kenso skips one already in the campaign. A contact whose country is unknown is kept. Empty (the default) blocks no country. |
| `kind` | string | Campaign type: `sales` or `recruiting`. Set when the campaign is created and cannot change. |
| `roleId` | integer (int64) | Id of the main role a recruiting campaign hires for. Null when none is set; always returned. |
| `mode` | string | How contacts enter the campaign: `batch` sends to a fixed set of contacts, and `trigger` adds contacts over time as signals come in. A batch campaign can become a trigger campaign, but not the other way round. |
| `autoLaunchWhenReady` | boolean | The campaign launches itself, and starts spending sending credits, once it reaches `ready`. Changing it needs the `launch` permission. |
| `launchAt` | string (date-time) | When the campaign is scheduled to launch (UTC). At that time Kenso launches it, or as soon as it reaches `ready` after that time; sends then follow the campaign's sending days, window and time zone. Set it with `PUT /v1/campaigns/{campaignId}/launch-schedule`. Omitted when no launch is scheduled, and once the campaign has launched. |
| `migration` | CampaignMigrationOrigin | Where an imported campaign came from. Omitted for campaigns made in Kenso. |
| `approvalsWaiting` | integer (int32) | First emails waiting for approval in the campaign's pending or rewriting batches. 0 when none. |
| `forecast` | CampaignForecast | Sending progress and the estimated finish. Returned while `sendingStatus` is `sending` or `paused` and a forecast under 24 hours old knows the remaining sends. Omitted for drafts, campaigns that have not started sending, completed and archived campaigns, trigger campaigns (they never finish) and campaigns with nothing planned. |
| `pausedReason` | CampaignPausedReason | Why sending is paused. Returned only while `sendingStatus` is `paused`. |
| `warmStart` | boolean | For the campaign's first days after launch (14 by default), its first emails go to its highest-scored contacts first (contacts without a lead score after them, in their usual order), at a low daily volume. Follow-ups keep their order. The window counts from launch, not from when this is turned on: turned on inside it, the lower volume starts that day; turned on after it, nothing changes. Off by default; duplicates, templates saved from the campaign and drafts made from those templates start with it off. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/campaigns/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 4821,
    "name": "Q4 SaaS founders",
    "status": "active",
    "channel": "email",
    "contactLimit": 2500,
    "contactLimitPeriod": "total",
    "contactLimitUsed": 1840,
    "contactLimitReached": false,
    "contactCount": 1840,
    "leadCount": 2115,
    "segmentCount": 2,
    "inboxCount": 6,
    "createdAt": "2026-09-23T15:02:11Z",
    "launchedAt": "2026-09-29T13:00:00Z",
    "sourceStatus": "done",
    "sendingStatus": "sending",
    "processingStatus": [
      "finished"
    ],
    "sendingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "sendingStartTime": "09:00",
    "sendingEndTime": "17:00",
    "sendingTimezone": "America/New_York",
    "maxEmailsPerDay": 300,
    "ownerMemberId": 1093,
    "stopOnReply": true,
    "stopCompanyOnReply": true,
    "groupSameCompanySends": true,
    "newLeadsFirst": false,
    "warmStart": false,
    "catchAllLaneEnabled": false,
    "sourceLanguage": "en",
    "languageMode": "source_only",
    "enabledLanguages": [],
    "formalityOverrides": {},
    "languageFallback": "source",
    "rampUpDays": 5,
    "trackClicks": false,
    "trackOpens": false,
    "unsubscribeLink": true,
    "sendAsPlainText": false,
    "protectAccountPlays": true,
    "excludedCountries": [],
    "kind": "sales",
    "mode": "batch",
    "autoLaunchWhenReady": false,
    "approvalsWaiting": 0,
    "forecast": {
      "plannedSendCount": 3680,
      "sentCount": 2208,
      "remainingSendCount": 1472,
      "progress": 0.6,
      "estimatedFinishAt": "2026-10-20T20:40:00Z",
      "effectiveDailyCapacity": 300,
      "calculatedAt": "2026-10-14T09:35:00Z"
    }
  }
}
```

## Types

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

### CampaignMigrationOrigin

The tool, account and campaign an imported campaign came from.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionId` | integer (int64) | no | Id of the import connection the campaign came through. |
| `vendor` | string | no | The tool the campaign was imported from: `instantly`, `smartlead`, `emailbison`, `salesforge`, `lemlist`, `apollo`, `replyio`, `salesloft` or `outreach`. |
| `sourceAccountId` | string | no | Id of the account in that tool. |
| `sourceCampaignId` | string | no | Id of the campaign in that tool. |
| `sourceStatus` | string | no | The campaign's status in that tool at the last sync, such as `active` or `paused`, or `unknown`. |
| `syncedAt` | string (date-time) | no | When Kenso last synced the campaign from that tool (UTC). Omitted before the first sync. |
| `cutoverAt` | string (date-time) | no | When sending is set to move from that tool to Kenso (UTC). Omitted when no switch-over time was set. |
| `historyFrom` | string | no | First day of the imported daily stats (`YYYY-MM-DD`). Null, not omitted, when no stats were imported. |
| `historyTo` | string | no | Last day of the imported daily stats (`YYYY-MM-DD`). Null when `historyFrom` is null. |

### CampaignForecast

How far a sending or paused campaign is through its planned emails, and when it should finish. Kenso refreshes the forecast every 5 minutes from the inboxes' daily capacity (shared with the workspace's other campaigns), `maxEmailsPerDay`, the sending days, window and time zone, and the waits between steps.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plannedSendCount` | integer (int32) | no | Emails planned for the whole campaign: `sentCount` plus `remainingSendCount`. |
| `sentCount` | integer (int32) | no | Emails sent so far. It comes from daily totals, so today's emails can appear the next day. |
| `remainingSendCount` | integer (int32) | no | Emails still planned, for the contacts in the campaign and the steps they have left. |
| `progress` | number (double) | no | Share of planned emails sent: `sentCount` divided by `plannedSendCount`, from 0 to 1 with four decimals. It measures emails sent, not the share of contacts reached. |
| `estimatedFinishAt` | string (date-time) | no | When the last planned email should go out (UTC). Returned only while the campaign is sending and every remaining email fits in the forecast. Omitted while paused, when no inbox has capacity for the campaign, when the sending window cannot be used, or when the finish is more than two years away. |
| `effectiveDailyCapacity` | integer (int32) | no | Emails per day the campaign gets while sending; 0 when no inbox has capacity for it. Omitted while paused, when unknown, and for about 5 minutes after a resume until the next forecast. |
| `calculatedAt` | string (date-time) | no | When the forecast was calculated (UTC). Always under 24 hours old; an older forecast is not returned. |

### CampaignPausedReason

Why a campaign's sending is paused, from what Kenso recorded when it stopped. A campaign is never paused for having no inboxes: a broken inbox leaves the campaign sending and shows on the inbox instead.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | What paused it: `user` (a member, or an agent acting for one), `bounce_guard` (too many hard bounces), `sending_error` (paused after repeated send failures; Kenso does not pause for send failures today, so a campaign whose sends keep failing stays sending and shows `sendingError` instead), `holiday` (the US holiday pause), `client_approval` (waiting for your client to approve changed copy or a contact list; approval resumes it, or leaves it paused for you to resume when it cannot send), `billing` (sending suspended for non-payment), `workspace_locked` (the workspace was deactivated or locked), `other` (another automatic pause) or `unknown` (no reason was recorded, as for pauses before Kenso recorded them). New values may be added. |
| `at` | string (date-time) | no | When sending stopped (UTC). Omitted when the time was not recorded. |
| `byMemberId` | integer (int64) | no | For `user` only: the member who paused the campaign, or for whom an agent paused it. Omitted when unknown. |
| `detail` | string | no | What was recorded, for display: the evidence for `bounce_guard` and `sending_error`, who paused it for `user` (for example "Jordan Lee via Claude Code"), or the system that paused it for `other`. Omitted for other kinds. |
