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

# Job postings: Search job postings

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

## Search job postings

`POST /v1/job-postings/search` - operationId `job-postings.search`

| Permission | Rate limit |
| --- | --- |
| Search view | 240 requests a minute per API key |

Search job postings with filters and get one page of postings. Use it to find companies that are hiring for a
role, in a place or on a date range.

Send at least one filter, for example `titles`, `location`, `hasRemote`, `postedWithin` (days)
or `status` (`open` by default, `closed` or `all`). `limit` sets the page size, from 1 to
50, and `cursor` takes the previous page's `pagination.next_cursor`. `groupBy: "company"` returns
one row per company. Request fields are camelCase, and the postings come back with snake_case fields such as
`posted_at`.

The search is free and does not use the export allowance.

Errors:

- `400 validation_failed`: a filter or `limit` is not valid.
- `402 plan_required`: the workspace's plan does not include job post search. `error.refusal` carries
the code `PLAN_FEATURE_NOT_AVAILABLE` and the feature `job_post_search`.
- `413 validation_failed`: the body is larger than 1 MB.
- `422 filter_required`: the body sets no filter.
- `503 service_unavailable`: job postings are not available right now. Try again.
- `504 upstream_timeout`: job postings took too long to answer. Try again.

Requires Search view.

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

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

| Field | Type | Description |
| --- | --- | --- |
| `signals` | array of JobPosting | The postings on this page, newest posted first. Present unless the search sets `groupBy` to `company`. |
| `companies` | array of JobPostingCompanyGroup | The hiring companies on this page, most matching postings first. Present only when `groupBy` is `company`. |
| `total` | integer (int64) | The postings that match across all pages, or the companies with `groupBy: "company"`. It stops at 1,000 when `totalMode` is `capped`, and is null when `totalMode` is `none`. |
| `totalMode` | string | How `total` was counted: `capped` (the default), `exact` or `none`. |
| `notes` | array of string | Notes about the answer, for example `total capped at 1000` when more postings match than `total` says. |
| `pagination` | JobPostingPagination | How to get the next page. |
| `facets` | JobPostingFacets | The matching postings counted by source, country, seniority, remote and status. Present only with `includeFacets: true`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/job-postings/search" \
  -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": {
    "signals": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "description_html": "string",
        "company": {
          "id": "string",
          "name": "string",
          "domain": "acme.com",
          "website_url": "https://example.com",
          "linkedin_url": "https://example.com",
          "ken_search_id": "string"
        },
        "company_name": "string",
        "company_domain": "acme.com",
        "location": "string",
        "locations": [
          "string"
        ],
        "country": "string",
        "remote": true,
        "workplace_type": "string",
        "department": "string",
        "team": "string",
        "employment_type": "string",
        "seniority": "string",
        "language": "string",
        "salary_raw": "string",
        "salary_currency": "USD",
        "salary_min": 0.5,
        "salary_max": 0.5,
        "salary_min_usd": 0.5,
        "salary_max_usd": 0.5,
        "equity": "string",
        "requisition_id": "string",
        "tags": [
          "string"
        ],
        "is_agency": true,
        "source": "string",
        "source_url": "https://example.com",
        "application_url": "https://example.com",
        "status": "string",
        "posted_at": "2026-09-23T15:02:11Z",
        "first_seen_at": "2026-09-23T15:02:11Z",
        "last_seen_at": "2026-09-23T15:02:11Z",
        "closed_at": "2026-09-23T15:02:11Z",
        "expires_at": "2026-09-23T15:02:11Z"
      }
    ],
    "companies": [
      {
        "company": {
          "id": "string",
          "name": "string",
          "domain": "acme.com",
          "website_url": "https://example.com",
          "linkedin_url": "https://example.com",
          "ken_search_id": "string"
        },
        "match_count": 1,
        "newest_posted_at": "2026-09-23T15:02:11Z",
        "sources": [
          "string"
        ],
        "titles": [
          "string"
        ]
      }
    ],
    "total": 1,
    "totalMode": "capped",
    "notes": [
      "string"
    ],
    "pagination": {
      "next_cursor": "eyJpZCI6ODE1fQ"
    },
    "facets": {
      "sources": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "countries": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "seniority": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "remote": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "status": [
        {
          "value": "string",
          "count": 1
        }
      ]
    }
  }
}
```

## Types

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

### JobPosting

An open or closed role a company published on its career site or a public job board.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The posting's id, as a string. Pass it to `GET /v1/job-postings/{jobPostingId}`. |
| `title` | string | no | The job title. |
| `description` | string | no | The job description as plain text. Left out when the search sets `includeDescription: false`, and null when unknown. |
| `description_html` | string | no | The job description as HTML. Left out when the search sets `includeDescription: false`, and null when unknown. |
| `company` | JobPostingCompany | no | The hiring company. Left out when the search sets `includeCompany: false`. |
| `company_name` | string | no | The hiring company's name. |
| `company_domain` | string | no | The hiring company's web domain, for example `acme.com`. Null when unknown. |
| `location` | string | no | The location as the posting states it. Null when it states none. |
| `locations` | array of string | no | Every location the posting lists. |
| `country` | string | no | The country of the job. Null when unknown. |
| `remote` | boolean | no | True when the job is remote, false when it is not. Null when the posting does not say. |
| `workplace_type` | string | no | The workplace type the posting states. Null when it states none. |
| `department` | string | no | The department the job is in. Null when unknown. |
| `team` | string | no | The team the job is in. Null when unknown. |
| `employment_type` | string | no | The employment type the posting states. Null when unknown. |
| `seniority` | string | no | The seniority of the role. Null when unknown. |
| `language` | string | no | The language the posting is written in. Null when unknown. |
| `salary_raw` | string | no | The salary text as the posting states it. Null when it states none. |
| `salary_currency` | string | no | The currency of `salary_min` and `salary_max`, for example `USD`. Null when unknown. |
| `salary_min` | number (double) | no | The lowest salary the posting states, in `salary_currency`. Null when unknown. |
| `salary_max` | number (double) | no | The highest salary the posting states, in `salary_currency`. Null when unknown. |
| `salary_min_usd` | number (double) | no | The lowest salary converted to US dollars. Null when unknown. |
| `salary_max_usd` | number (double) | no | The highest salary converted to US dollars. Null when unknown. |
| `equity` | string | no | The equity text as the posting states it. Null when it states none. |
| `requisition_id` | string | no | The employer's own requisition id for the job. Null when unknown. |
| `tags` | array of string | no | The tags the posting carries on its source. |
| `is_agency` | boolean | no | True when the hiring company is a recruiting or staffing agency. |
| `source` | string | no | The career site or job board Kenso read the posting from. |
| `source_url` | string | no | The posting's URL on its source. Null when unknown. |
| `application_url` | string | no | The URL to apply for the job. Null when unknown. |
| `status` | string | no | `open` while the posting is live and not expired, else `closed`. |
| `posted_at` | string (date-time) | no | When the employer posted the job, UTC. Null when the source does not say. |
| `first_seen_at` | string (date-time) | no | When Kenso first saw the posting, UTC. |
| `last_seen_at` | string (date-time) | no | When Kenso last saw the posting on its source, UTC. |
| `closed_at` | string (date-time) | no | When the posting closed, UTC. Null while it is open. |
| `expires_at` | string (date-time) | no | When the posting expires, UTC. Null when it has no end date. |

### JobPostingCompanyGroup

A hiring company on a `groupBy: "company"` search page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `company` | JobPostingCompany | no | The company. |
| `match_count` | integer (int64) | no | How many of the company's postings match the search. |
| `newest_posted_at` | string (date-time) | no | When the company's newest matching posting was posted, UTC. Null when no matching posting says. |
| `sources` | array of string | no | The sources of the company's matching postings. |
| `titles` | array of string | no | Up to 20 distinct titles of the company's matching postings. |

### JobPostingPagination

How to get the next page of job postings.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next_cursor` | string | no | Send it as `cursor` with the same filters to get the next page. Null on the last page. |

### JobPostingFacets

The matching postings counted by facet, each list largest count first.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sources` | array of JobPostingValueCount | no | The matching postings per source. |
| `countries` | array of JobPostingValueCount | no | The matching postings per country code. A posting in several countries counts in each. |
| `seniority` | array of JobPostingValueCount | no | The matching postings per seniority, without postings of unknown seniority. |
| `remote` | array of JobPostingValueCount | no | The matching postings per remote value, `true` or `false`. |
| `status` | array of JobPostingValueCount | no | The matching postings per status, `open` or `closed`. |

### JobPostingCompany

The company that published a job posting.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The company's id in the job postings index, as a string. The `companies.ids` filter takes it. |
| `name` | string | no | The company's name. |
| `domain` | string | no | The company's web domain, for example `acme.com`. Null when unknown. |
| `website_url` | string | no | The company's website URL. Null when unknown. |
| `linkedin_url` | string | no | The company's LinkedIn page URL. Null when unknown. |
| `ken_search_id` | string | no | The company's Kenso company id (`kenCompanyId` elsewhere in the API), as a string. Null when Kenso has not matched the company. |

### JobPostingValueCount

A value and how many job postings have it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | no | The value, as the matching filter takes it. |
| `count` | integer (int64) | no | How many postings have the value: matching postings in a facet, open postings in a filter suggestion. |
