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

# Placement tests: Get a placement test

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

## Get a placement test

`GET /v1/placement-tests/{placementTestId}` - operationId `placement-tests.get`

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

Returns one placement test with its full results. Poll it after you start a test, until `status` is
`completed` or `failed`.

Besides the fields in the list, the test has `type`, `senderInboxIds`, the `subject` and
`body` it sent, and `openPixelHost` when it carried the open pixel. Once the test completes, it also
has `startedAt`, `sentCount`, `counts`, and the results per seed provider (`providers`),
per sending inbox (`senders`) and per seed mailbox (`seeds`), plus any `errors` the provider
reported. Seed addresses are masked. Rates are fractions from 0 to 1.

The `earlierTests` list holds up to 10 earlier tests of the same `campaignId` and `domainId`,
whichever are set, newest first, so you can show a trend. A test of one inbox that has no domain has no earlier tests.

Errors:

- `404 not_found`: the placement test is not in this workspace.

Requires Delivery view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/placement-tests/GET/v1/placement-tests/%7BplacementTestId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `placementTestId` | path | integer (int64) | yes | The placement test's id. |
| `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 `PlacementTest`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | Placement test id. |
| `campaignId` | integer (int64) | Campaign the test belongs to. In a campaign's list, a weekly domain test can belong to another campaign that sends from the same domain. |
| `listedForCampaignId` | integer (int64) | The campaign whose list this item is in, when you list several campaigns with `campaignIds`. Omitted everywhere else. |
| `inboxId` | integer (int64) | Inbox the test was limited to. Omitted for a test of a whole domain. |
| `domainId` | integer (int64) | Domain the test sent from. Omitted when the test has no domain. |
| `sequenceId` | integer (int64) | Sequence whose copy the test sent. Omitted in the answer to a start and when not recorded. |
| `sequenceVersionId` | integer (int64) | Saved sequence version the test sent. Omitted when the test sent the sequence as it was saved at the time. |
| `status` | string | Test status: `pending` (waiting to send), `running` (sent, and Kenso is checking the seed mailboxes), `completed` or `failed`. |
| `inboxRate` | number (double) | Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes. |
| `spamRate` | number (double) | Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes. |
| `categoryRate` | number (double) | Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted until the test completes. |
| `missingRate` | number (double) | Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes. |
| `code` | string | The testing provider's reference for this test. Omitted when there is none. |
| `openPixelHost` | string | Host the campaign open pixel loaded from, for a test started with `openPixel` set to true. Returned when you start a test and when you get one, not in the list. Omitted when the test carried no pixel. |
| `provider` | string | Name of the testing provider that ran the test, in lowercase, such as `kenso` for a test on the Kenso seed network. Omitted when not recorded. Prefer providerKind. |
| `providerKind` | string | The testing provider in neutral words: `kenso` for the Kenso seed network, `mailbox_provider` for the mailbox provider's engine, or `other` (older tests). Omitted when not recorded. |
| `scope` | string | Kenso tests: `inbox`, `domain` or `campaign` (the campaign's senders). Omitted otherwise. |
| `verdict` | PlacementVerdict | Kenso tests: the scored cause and its one-line summary. Omitted until the test completes. |
| `hasControl` | boolean | Kenso tests: true when the test also sent the plain control message. Omitted on other tests. |
| `trackLinks` | boolean | Kenso tests: false when the test sent the body's links as written, true when it sent them as tracked links. Omitted on other tests. |
| `providersTested` | array of string | Kenso tests: the seed providers it sent to, `google_workspace` and `microsoft_365`. |
| `dataPoints` | array of PlacementProviderBreakdown | Inbox rate by type of seed mailbox, as a list with one entry. Omitted when the test has no results by provider. |
| `createdAt` | string (date-time) | When the test was created, in UTC. |
| `completedAt` | string (date-time) | When the test completed, in UTC. Omitted until then. |
| `type` | string | Kind of test: `weekly` (Kenso's weekly test of a sending domain), `on_demand` (a test someone started) or `pre_launch` (a test run before a campaign launched). Only when you get one test. |
| `startedAt` | string (date-time) | When the provider started sending the test, in UTC. Omitted until the test completes. |
| `sentCount` | integer (int32) | Test emails the provider sent. 0 when it sent none, for example because it refused every sending inbox (see `errors`). Omitted until the test completes. |
| `failureReason` | string | Why the test failed, when `status` is `failed`. Omitted otherwise. |
| `senderInboxIds` | array of integer (int64) | Ids of the inboxes the test sent from. Omitted when not recorded. |
| `subject` | string | Subject line the test sent, with its variables filled. Omitted for older tests that did not store it. |
| `body` | string | Body the test sent, with its variables filled. Omitted for older tests that did not store it. |
| `counts` | PlacementCounts | Seed copies per placement across the whole test. Omitted until the test completes. |
| `providers` | array of PlacementProviderResult | Seed copies per placement for each seed mailbox provider, in the order `gmail`, `google_workspace`, `outlook`, `microsoft_365`, then any other. Omitted until the test completes. |
| `senders` | array of PlacementSenderResult | Seed copies per placement for each sending inbox, including an inbox whose mail reached no seed. Omitted until the test completes. |
| `seeds` | array of PlacementSeedResult | One row per seed mailbox and sending inbox. Omitted until the test completes. |
| `errors` | array of PlacementTestError | Errors the provider reported, such as a sending inbox it could not use, oldest first and at most 50. On a Kenso test, the seed providers it skipped and the sends and reads that failed. Omitted when there are none. |
| `control` | PlacementControl | Kenso detail with `hasControl`: the control arm's rates, counts and providers. |
| `progress` | PlacementProgress | Kenso detail: sends by state and when the final read is due. |
| `followUp` | PlacementFollowUp | Kenso tests started with `followUp`: its settings, and on one test its body and results. The other result fields describe the first email. Omitted on other tests. |
| `earlierTests` | array of PlacementTestTrend | Up to 10 earlier tests of the same `campaignId` and `domainId`, whichever are set, newest first. Empty for a test of one inbox that has no domain. Only when you get one test. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/placement-tests/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": 812,
    "campaignId": 812,
    "listedForCampaignId": 812,
    "inboxId": 812,
    "domainId": 812,
    "sequenceId": 812,
    "sequenceVersionId": 812,
    "status": "string",
    "inboxRate": 0.5,
    "spamRate": 0.5,
    "categoryRate": 0.5,
    "missingRate": 0.5,
    "code": "string",
    "openPixelHost": "string",
    "provider": "kenso",
    "providerKind": "string",
    "scope": "inbox",
    "verdict": {
      "cause": "string",
      "summary": "string"
    },
    "hasControl": true,
    "trackLinks": true,
    "providersTested": [
      "string"
    ],
    "dataPoints": [
      {
        "googleWorkspace": 0.5,
        "googlePersonal": 0.5,
        "outlookWorkspace": 0.5,
        "outlookPersonal": 0.5
      }
    ],
    "createdAt": "2026-09-23T15:02:11Z",
    "completedAt": "2026-09-23T15:02:11Z",
    "type": "string",
    "startedAt": "2026-09-23T15:02:11Z",
    "sentCount": 1,
    "failureReason": "string",
    "senderInboxIds": [
      812
    ],
    "subject": "string",
    "body": "string",
    "counts": {
      "inbox": 1,
      "promotions": 1,
      "other": 1,
      "spam": 1,
      "missing": 1,
      "total": 1
    },
    "providers": [
      {
        "provider": "gmail",
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1,
        "tested": true,
        "folders": {
          "key": 1
        },
        "authentication": {
          "checked": 1,
          "spfPass": 1,
          "dkimPass": 1,
          "dmarcPass": 1,
          "compauthPass": 1,
          "allPass": 1
        },
        "microsoft": {
          "scored": 1,
          "bulkHigh": 1,
          "medianBcl": 0.5,
          "medianScl": 0.5
        },
        "medianArrivalSeconds": 1
      }
    ],
    "senders": [
      {
        "email": "jane@example.com",
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      }
    ],
    "seeds": [
      {
        "seed": "d***@gmail.com",
        "provider": "gmail",
        "senderEmail": "jane@example.com",
        "placement": "inbox",
        "folder": "SPAM",
        "detectedAt": "2026-09-23T15:02:11Z",
        "arm": "main",
        "status": "waiting",
        "tab": "primary",
        "authentication": {
          "spf": "string",
          "dkim": "string",
          "dmarc": "string",
          "compauth": "string"
        },
        "microsoft": {
          "scl": 1,
          "bcl": 1,
          "cat": "string",
          "sfv": "string"
        },
        "arrivalSeconds": 1,
        "followUp": {}
      }
    ],
    "errors": [
      {
        "message": "string",
        "at": "2026-09-23T15:02:11Z"
      }
    ],
    "control": {
      "inboxRate": 0.5,
      "spamRate": 0.5,
      "categoryRate": 0.5,
      "missingRate": 0.5,
      "counts": {
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      },
      "providers": [
        {
          "provider": "gmail",
          "inbox": 1,
          "promotions": 1,
          "other": 1,
          "spam": 1,
          "missing": 1,
          "total": 1,
          "tested": true,
          "folders": {
            "key": 1
          },
          "authentication": {
            "checked": 1,
            "spfPass": 1,
            "dkimPass": 1,
            "dmarcPass": 1,
            "compauthPass": 1,
            "allPass": 1
          },
          "microsoft": {
            "scored": 1,
            "bulkHigh": 1,
            "medianBcl": 0.5,
            "medianScl": 0.5
          },
          "medianArrivalSeconds": 1
        }
      ]
    },
    "progress": {
      "planned": 1,
      "sent": 1,
      "read": 1,
      "waiting": 1,
      "failed": 1,
      "finalBy": "2026-09-23T15:02:11Z"
    },
    "followUp": {
      "format": "plain",
      "delayMinutes": 1,
      "subject": "string",
      "body": "string",
      "counts": {
        "inbox": 1,
        "promotions": 1,
        "other": 1,
        "spam": 1,
        "missing": 1,
        "total": 1
      },
      "providers": [
        {
          "provider": "gmail",
          "inbox": 1,
          "promotions": 1,
          "other": 1,
          "spam": 1,
          "missing": 1,
          "total": 1,
          "tested": true,
          "folders": {
            "key": 1
          },
          "authentication": {
            "checked": 1,
            "spfPass": 1,
            "dkimPass": 1,
            "dmarcPass": 1,
            "compauthPass": 1,
            "allPass": 1
          },
          "microsoft": {
            "scored": 1,
            "bulkHigh": 1,
            "medianBcl": 0.5,
            "medianScl": 0.5
          },
          "medianArrivalSeconds": 1
        }
      ]
    },
    "earlierTests": [
      {
        "id": 812,
        "campaignId": 812,
        "inboxId": 812,
        "domainId": 812,
        "status": "pending",
        "inboxRate": 0.5,
        "spamRate": 0.5,
        "categoryRate": 0.5,
        "missingRate": 0.5,
        "createdAt": "2026-09-23T15:02:11Z",
        "completedAt": "2026-09-23T15:02:11Z"
      }
    ]
  }
}
```

## Types

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

### PlacementVerdict

A Kenso test's verdict. `cause`: `auth_failing`, `copy`, `reputation`, `microsoft_bulk`, `one_provider`, `healthy` or `mixed`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cause` | string | no |  |
| `summary` | string | no |  |

### PlacementProviderBreakdown

Inbox rate by type of seed mailbox, each a fraction from 0 to 1. A field is omitted when the test had no seed mailboxes of that type.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `googleWorkspace` | number (double) | no | Inbox rate at Google Workspace seed mailboxes. |
| `googlePersonal` | number (double) | no | Inbox rate at personal Gmail seed mailboxes. |
| `outlookWorkspace` | number (double) | no | Inbox rate at Microsoft 365 seed mailboxes. |
| `outlookPersonal` | number (double) | no | Inbox rate at personal Outlook seed mailboxes. |

### PlacementCounts

Seed copies per placement. `total` is the sum of the other five counts.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies, the sum of the five counts. |

### PlacementProviderResult

Seed copies per placement at one seed mailbox provider.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | no | Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`. `unknown` when the testing provider did not say. |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies to this provider, the sum of the five counts. |
| `tested` | boolean | no | Kenso: false when the test sent nothing to this provider (not in the seed network yet), with zero counts. |
| `folders` | map of integer (int32) | no | Kenso: found messages per folder or tab, such as `primary` or `junk`, plus `missing`. |
| `authentication` | PlacementAuthSummary | no | Kenso: SPF, DKIM, DMARC and compauth over the found messages that carry them. |
| `microsoft` | PlacementMicrosoftSummary | no | Kenso, `microsoft_365` only: Microsoft's spam (SCL) and bulk (BCL) scores. |
| `medianArrivalSeconds` | integer (int32) | no | Kenso: median seconds from send to arrival over found messages. |

### PlacementSenderResult

Seed copies per placement for one sending inbox.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | no | Address of the sending inbox, in lowercase. |
| `inbox` | integer (int32) | no | Copies that landed in the inbox (the primary tab in Gmail). |
| `promotions` | integer (int32) | no | Copies that landed in the promotions tab or another category tab. |
| `other` | integer (int32) | no | Copies that landed in any other folder. |
| `spam` | integer (int32) | no | Copies that landed in spam or junk. |
| `missing` | integer (int32) | no | Copies that never arrived. |
| `total` | integer (int32) | no | All copies from this inbox, the sum of the five counts. 0 when its mail reached no seed. |

### PlacementSeedResult

Where one seed mailbox received the copy from one sending inbox.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seed` | string | no | Seed address, masked to its first letter and its domain, such as `d***@gmail.com`. Kenso staff see it in full. |
| `provider` | string | no | Seed mailbox provider, such as `gmail`, `google_workspace`, `outlook` or `microsoft_365`. |
| `senderEmail` | string | no | Address of the sending inbox, in lowercase. |
| `placement` | string | no | Where the copy landed: `inbox`, `promotions`, `other`, `spam` or `missing`, or `pending` on a Kenso seed not read yet. |
| `folder` | string | no | Gmail label or Outlook folder the copy landed in, such as `SPAM` or `Junk Email`. Omitted when not reported. |
| `detectedAt` | string (date-time) | no | When the copy was found in the seed mailbox, in UTC. Omitted when not reported. |
| `arm` | string | no | Kenso: `main` or `control`. |
| `status` | string | no | Kenso: `waiting`, `found`, `missing`, `send_failed` or `read_failed`. |
| `tab` | string | no | Kenso: the folder or tab the message was in, such as `primary`, `promotions` or `junk`. |
| `authentication` | PlacementSeedAuth | no | One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like. |
| `microsoft` | PlacementSeedMicrosoft | no | Kenso, Microsoft 365 seeds: the message's SCL, BCL, CAT and SFV. |
| `arrivalSeconds` | integer (int32) | no |  |
| `followUp` | PlacementSeedResult | no | Kenso, a test with a follow-up: where the follow-up to this seed landed, in this same shape. Omitted otherwise. |

### PlacementTestError

An error the testing provider reported for a placement test.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | no | The provider's error text, at most 500 characters. |
| `at` | string (date-time) | no | When the error happened, in UTC. Omitted when not reported. |

### PlacementControl

The control arm: the same senders sent a plain message. Rates are fractions from 0 to 1.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inboxRate` | number (double) | no |  |
| `spamRate` | number (double) | no |  |
| `categoryRate` | number (double) | no |  |
| `missingRate` | number (double) | no |  |
| `counts` | PlacementCounts | no | Seed copies per placement. `total` is the sum of the other five counts. |
| `providers` | array of PlacementProviderResult | no |  |

### PlacementProgress

A Kenso test's sends by state: `read` found or missing, `waiting` not read yet, `failed` not sent or not readable. `finalBy` is when the last read is due while anything waits.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `planned` | integer (int32) | no |  |
| `sent` | integer (int32) | no |  |
| `read` | integer (int32) | no |  |
| `waiting` | integer (int32) | no |  |
| `failed` | integer (int32) | no |  |
| `finalBy` | string (date-time) | no |  |

### PlacementFollowUp

A Kenso test's follow-up, sent from the same inbox to the same seed in the first email's thread.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | no | `plain` or `html`. |
| `delayMinutes` | integer (int32) | no | Minutes after the first email was sent that the follow-up went out. |
| `subject` | string | no | Subject the follow-up sent, before its variables were filled. |
| `body` | string | no | Body the follow-up sent, before its variables were filled. Only when you get one test. |
| `counts` | PlacementCounts | no | Follow-ups per placement. Only when you get one test. |
| `providers` | array of PlacementProviderResult | no | The follow-up's results by seed provider. Only when you get one test. |

### PlacementTestTrend

An earlier placement test, for a trend. Rates are fractions from 0 to 1.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | Placement test id. |
| `campaignId` | integer (int64) | no | Campaign the earlier test belongs to. |
| `inboxId` | integer (int64) | no | Inbox the earlier test was limited to. Omitted for a test of a whole domain. |
| `domainId` | integer (int64) | no | Domain the earlier test sent from. Omitted when it has no domain. |
| `status` | string | no | Test status: `pending`, `running`, `completed` or `failed`. |
| `inboxRate` | number (double) | no | Share of the seed copies that landed in the inbox, a fraction from 0 to 1. Omitted until the test completes. |
| `spamRate` | number (double) | no | Share of the seed copies that landed in spam, a fraction from 0 to 1. Omitted until the test completes. |
| `categoryRate` | number (double) | no | Share of the seed copies that landed in a promotions or other category tab, a fraction from 0 to 1. Omitted until the test completes. |
| `missingRate` | number (double) | no | Share of the seed copies that never arrived, a fraction from 0 to 1. Omitted until the test completes. |
| `createdAt` | string (date-time) | no | When the earlier test was created, in UTC. |
| `completedAt` | string (date-time) | no | When the earlier test completed, in UTC. Omitted until then. |

### PlacementAuthSummary

Found messages that carry authentication results, and how many passed each check.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checked` | integer (int32) | no |  |
| `spfPass` | integer (int32) | no |  |
| `dkimPass` | integer (int32) | no |  |
| `dmarcPass` | integer (int32) | no |  |
| `compauthPass` | integer (int32) | no |  |
| `allPass` | integer (int32) | no | Messages where SPF, DKIM and DMARC all passed. |

### PlacementMicrosoftSummary

Microsoft's scores over found Microsoft 365 messages. `bulkHigh`: messages with a high bulk score.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scored` | integer (int32) | no |  |
| `bulkHigh` | integer (int32) | no |  |
| `medianBcl` | number (double) | no |  |
| `medianScl` | number (double) | no |  |

### PlacementSeedAuth

One message's authentication results: `pass`, `fail`, `softfail`, `none` and the like.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `spf` | string | no |  |
| `dkim` | string | no |  |
| `dmarc` | string | no |  |
| `compauth` | string | no |  |

### PlacementSeedMicrosoft

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scl` | integer (int32) | no |  |
| `bcl` | integer (int32) | no |  |
| `cat` | string | no |  |
| `sfv` | string | no |  |
