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

# People and company search: Expand job titles

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

## Expand job titles

`POST /v1/search/people/expand-titles` - operationId `search.expand-titles`

| Permission | Rate limit |
| --- | --- |
| Search view | 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day) |

Get related job titles for the titles you send, so a people search also finds the same role under other names.

Send `titles`, a list of up to 50 job titles. The answer's `expandedTitles` maps each title you sent to
its related titles. `error` says why when the expansion failed.

Kenso runs an AI model for each expansion. The same body in the same workspace within an hour gets the earlier
answer at no cost. Any other call takes one unit of the workspace's `aiSearchExpand` quota: 20 a minute and
500 a day, shared with industry expansion.

Errors:

- `400 validation_failed`: `titles` is not valid, for example more than 50 titles.
- `429 quota_exceeded`: the workspace used its `aiSearchExpand` quota. Retry after the
`Retry-After` header.

Requires Search view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/search/POST/v1/search/people/expand-titles)

### 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`. |

### Response 200

`data` is a `SearchPeopleTitleExpansion`.

| Field | Type | Description |
| --- | --- | --- |
| `expandedTitles` | map of array of string | Each title you sent, mapped to its related job titles. |
| `error` | string | Why the expansion failed, when the AI model gave no usable answer. Null otherwise. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/search/people/expand-titles" \
  -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": {
    "expandedTitles": {
      "key": [
        "string"
      ]
    },
    "error": "string"
  }
}
```
