# ClearedJobs Search

## Overview

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

## Description

Search cleared jobs by keyword. Only the first HTML page is available, so pagination.next is null and page 2 returns 404.

## 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/clearedjobs/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### analyst

```json
{
  "results": [
    {
      "id": "1902823",
      "url": "https://clearedjobs.net/job/analyst-washington-district-of-columbia-1902823",
      "logo": "https://assets.webscribble.com/cdn-cgi/image/width=90,fit=scale-down,format=auto/https://wjm.s3.amazonaws.com/cjng/uploads/KoniagInc-100.jpg",
      "title": "Analyst",
      "posted": "October 16, 2026",
      "company": "Koniag Government Services",
      "location": "Washington, District of Columbia",
      "security_clearance": "Public Trust"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 25,
    "total_pages": null,
    "total_results": 3170
  }
}
```

## Documentation

## Overview
Search cleared jobs on clearedjobs.net. `query` is a keyword, a jobs URL with `keywords`, or a page such as `q-analyst-jobs.html`. A job URL (`/job/...`) returns 400. Use the job endpoint for that URL.

Only the first HTML page is available. `pagination.next` is null even when `total_results` is larger than the cards returned. Do not invent a next URL. `page` above 1 returns 404. `total_pages` is null.

## Quickstart
```
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/clearedjobs/search?query=analyst"
```

## Parameters
| Name | Detail |
|---|---|
| query | Required string. Keyword or a clearedjobs.net jobs URL. Example: `analyst`. A job URL returns 400. |
| page | Optional integer. Only page 1 is served. Example: `1`. `page=2` returns 404. |

## Response fields
| Name | Detail |
|---|---|
| results[].id | String. Job id. The slug on `url` ends with this id. |
| results[].title | String. |
| results[].url | String. Pass this URL to the job endpoint. |
| results[].company | String or null. |
| results[].location | String or null. |
| results[].security_clearance | String or null. For example `Public Trust`. |
| results[].posted | String or null. Display date from the card, for example `October 16, 2026`. |
| results[].logo | String or null. |
| pagination.page | Integer. Always 1 on a successful search. |
| pagination.per_page | Integer. Number of cards in this HTML page. |
| pagination.total_results | Integer or null. The `Found N Jobs` count. It can be much larger than `per_page`. |
| pagination.total_pages | Null. Further pages are not in the HTML. |
| pagination.next | Null. There is no next URL to follow. |

## Pagination
`next` is null because only the first HTML page is available. That is true even when `total_results` is in the thousands and `per_page` is about 25. `total_pages` is null. Requesting `page=2` returns 404. Ids on the page are unique. Open each `url` with the job endpoint for the posting text.

## Use cases
- A cleared staffing desk lists the first page of `analyst` roles and reads `security_clearance` on each card.
- A job board passes every `url` to the job endpoint. It does not request page 2.
- A market scan stores `total_results` as the site's found count and treats the returned cards as the only page.

## Error codes
| Name | Detail |
|---|---|
| 400 | Missing `query`, a host other than clearedjobs.net, or a job URL sent to search. |
| 404 | No jobs, or `page` above 1. |
| 401 | Missing API key. |
| 500 | The ClearedJobs request failed. |

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