# Greenhouse Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/greenhouse/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/greenhouse-search |

## Description

List jobs on a Greenhouse board. query is the board token, such as discord. keyword filters title and location.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/greenhouse/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### discord

```json
{
  "results": [
    {
      "id": 8806482002,
      "url": "https://job-boards.greenhouse.io/discord/jobs/8806482002",
      "title": "Commercial Policy Lead",
      "language": "en",
      "location": "San Francisco Bay Area",
      "updated_at": "2026-10-20T20:27:20-04:00",
      "company_name": "Discord",
      "requisition_id": "R-107406",
      "first_published": "2026-09-15T12:52:11-04:00",
      "application_deadline": null
    }
  ],
  "pagination": {
    "next": "https://job-boards.greenhouse.io/discord?page=2",
    "page": 1,
    "per_page": 20,
    "total_pages": 3,
    "total_results": 43
  }
}
```

## Documentation

## Overview
List open jobs on a public Greenhouse board. `query` is the board token, such as `discord`, or `https://job-boards.greenhouse.io/discord`. Optional `keyword` filters title and location. A job URL, or `discord/{job id}`, returns 400 here. Pass that value to the job endpoint.

Greenhouse returns the whole board. This endpoint slices it into pages of 20.

## Quickstart
```
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/greenhouse/search?query=discord"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/greenhouse/search?query=discord&page=2"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/greenhouse/search?query=discord&keyword=policy"
```

## Parameters
| Name | Detail |
|---|---|
| query | Required string. Board token or a job-boards.greenhouse.io board URL. Example: `discord`. A job URL returns 400. |
| keyword | Optional string. Case-insensitive filter on title and location. Example: `policy`. |
| page | Optional integer from 1. Example: `2`. Defaults to 1. |

## Response fields
| Name | Detail |
|---|---|
| results[].id | Integer. Greenhouse job id. Pass `discord/{id}` to the job endpoint. |
| results[].title | String. |
| results[].company_name | String or null. |
| results[].location | String or null. |
| results[].url | String or null. Public job URL. |
| results[].updated_at | String or null. |
| results[].first_published | String or null. |
| results[].requisition_id | String or null. |
| results[].language | String or null. |
| results[].application_deadline | String or null. |
| pagination.page | Integer. |
| pagination.per_page | Integer. 20. |
| pagination.total_results | Integer. Jobs on the board after the keyword filter. |
| pagination.total_pages | Integer. |
| pagination.next | String or null. `https://job-boards.greenhouse.io/discord?page=2`, with `keyword` when you set one. Null on the last page. |

## Pagination
Page size is 20. The Discord board currently needs more than one page, so `pagination.next` is `https://job-boards.greenhouse.io/discord?page=2`. Request `page=2` for the next slice. Job ids do not repeat across pages. `next` is null when the filtered list fits on the current page. `keyword=policy` on Discord is a one-page filter, so `next` is null and `total_results` is the number of title or location matches.

## Use cases
- A recruiting ops team exports every open role on the `discord` board by following `pagination.next`.
- A policy newsletter calls `query=discord&keyword=policy` and stops when `next` is null.
- A careers aggregator stores `id` and `url`, then fetches the posting text from the job endpoint.

## Error codes
| Name | Detail |
|---|---|
| 400 | Missing board, a host other than greenhouse.io, or a job URL sent to search. |
| 404 | Unknown board, no jobs, or `page` past the last page. |
| 401 | Missing API key. |
| 500 | The Greenhouse request failed. |

## Related endpoints
- [Greenhouse Job](https://www.piloterr.com/library/greenhouse-job)