# USAJOBS Federal Vacancy & Pay Grade Finder (`dataspryva/usajobs-federal-vacancy-and-pay-grade-finder`) Actor

Search USAJOBS federal postings by keyword, location, agency, GS pay grade and schedule, with salary range, qualifications, security clearance status and remote eligibility for each vacancy.

- **URL**: https://apify.com/dataspryva/usajobs-federal-vacancy-and-pay-grade-finder.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Jobs, Automation, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## USAJOBS Federal Vacancy & Pay Grade Finder

USAJOBS is the US government's official federal job board. This actor reads its live public search and announcement pages directly, so it returns federal vacancies, pay scales and grades, salary ranges, hiring paths, clearance requirements and full announcement text **with no API key, login or cookie**.

### What this actor does

- Searches current federal postings by keyword, location, agency or parent department, occupational series, GS-equivalent grade range, work schedule, hiring path, clearance, appointment type, travel, work site (remote / telework / exclude remote), relocation assistance and minimum salary.
- Pages through the full result set (up to USAJOBS's own 10,000-result ceiling), removes duplicate postings and stops at `maxItems`.
- Optionally opens each posting's announcement page to add duties, qualifications, education, evaluation criteria, exact salary range, promotion potential and remote/telework status.
- Reads individual announcement links in **Job Details** mode, so you can enrich a list of job URLs you already collected.
- Keeps the older input keys (`organization`, `positionSchedule`, `whoMayApply`, `gradeMin`, `gradeMax`, `apiKey`, `datePostedDays`) working in code, so saved tasks keep running.

### Modes

| Mode | What it returns | Main inputs |
| --- | --- | --- |
| **Search federal job postings** (`searchJobs`) | A record per matching vacancy from the live USAJOBS search. | `keyword`, `locationName`, `agency`, `department`, `jobCategoryCode`, grade range, schedule, hiring path, clearance, job type, travel, work site, salary, sort. |
| **Get details for specific job links** (`jobDetails`) | A full record for each announcement URL or control number you supply. | `jobUrls` (or `documentId` in the link), `maxItems`. |

#### Example: software engineer roles, GS 9-12, open to the public

```json
{
  "mode": "searchJobs",
  "keyword": "software engineer",
  "gradeMin": 9,
  "gradeMax": 12,
  "hiringPath": "public",
  "includeDetails": true,
  "maxItems": 50
}
```

#### Example: remote data roles at a named agency

```json
{
  "mode": "searchJobs",
  "keyword": "data analyst",
  "agency": "NASA",
  "workSite": "remote",
  "sortBy": "recentlyPosted",
  "maxItems": 100
}
```

#### Example: enrich two job links

```json
{
  "mode": "jobDetails",
  "jobUrls": [
    "https://www.usajobs.gov/job/893002300",
    "https://www.usajobs.gov/job/892113500"
  ]
}
```

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Select | `searchJobs` | Search postings or read specific job links. |
| `keyword` | String | – (prefill: `software engineer`) | Job title, skill or keyword. Leave empty to browse all postings. |
| `locationName` | String | – | City, state or country, e.g. `Washington, DC` or `Germany`. |
| `department` | String | – | Parent department name, acronym or code, e.g. `Department of Defense`, `DOD` or `DD`. Comma-separate multiple values. |
| `agency` | String | – | Agency or department name, acronym or code, e.g. `NASA`, `Department of the Navy` or `NV27`. Comma-separate multiple values. |
| `jobCategoryCode` | String | – | Four-digit occupational series codes, comma-separated (e.g. `2210` for IT, `0343` for management analysis). |
| `gradeMin` / `gradeMax` | Integer | – | GS-equivalent grade range, 1-15. |
| `schedule` | Select | Any | Full-time, part-time, shift work, intermittent, job sharing or multiple schedules. |
| `hiringPath` | Select | Any | Public, competitive service, excepted service, internal, transition, veterans, military spouses, students, graduates, disability, overseas, special authorities and more. |
| `securityClearance` | Select | Any | Not required, confidential, secret, top secret, SCI, Q/L access or other. |
| `jobType` | Select | Any | Permanent, temporary, term, detail, seasonal, summer, internships, recent graduates and more. |
| `travelPercentage` | Select | Any | None, occasional, or 25/50/75/76%+ travel. |
| `workSite` | Select | Any | Remote jobs only, exclude remote jobs, or telework-eligible jobs. |
| `relocationAssistance` | Boolean | `false` | Only postings that reimburse relocation. |
| `minSalary` | Integer | – | Minimum advertised annual salary in USD. |
| `sortBy` | Select | – (relevance) | Recently posted, closing soon, highest salary or lowest salary. |
| `includeDetails` | Boolean | `true` | Open each announcement for duties, qualifications, education and exact salary range. Turn off for faster, lighter runs. |
| `jobUrls` | String list | – | In Job Details mode: `https://www.usajobs.gov/job/<id>` links or bare control numbers. |
| `maxItems` | Integer | `50` | Maximum records to return (1-5,000). |

### Output per posting

| Field | Description |
| --- | --- |
| `positionId` | The agency announcement number (e.g. `27-DO-13105675-DH`). |
| `documentId` | USAJOBS control number; also the ID in the job URL. |
| `positionTitle` | Job title. |
| `positionUri` / `sourceUrl` | Clean canonical link to the announcement. |
| `organizationName` / `subAgency` / `departmentName` | Hiring agency, sub-agency and parent department. |
| `hiringOrganization` | Hiring organization exactly as published in the announcement metadata. |
| `locationName` / `locationDisplay` | Primary duty station and the display form with extra locations. |
| `positionLocalities` / `positionLocationCount` | Every duty station listed and how many there are. |
| `positionStartDate` / `datePosted` / `applicationCloseDate` | Open date, posted date and application deadline (ISO dates). |
| `salaryMin` / `salaryMax` | Advertised salary range in the stated unit. |
| `salaryCurrency` / `salaryUnit` | `USD` and `year` or `hour`. |
| `payScale` / `payGradeMin` / `payGradeMax` | Pay plan and grade range, e.g. `GS` 13-14 or `NF` 4. |
| `promotionPotential` | Highest grade the posting can promote to. |
| `positionSchedule` / `appointmentType` / `travelRequirement` | Work schedule, appointment type and travel requirement. |
| `whoMayApply` / `hiringPaths` / `hiringPathCodes` | First eligible audience plus every hiring path, as labels and codes. |
| `relocationReimbursed` | Whether relocation expenses are reimbursed. |
| `securityClearance` / `securityClearanceRequired` | Clearance text and a simple required/not-required flag. |
| `remoteIndicator` / `teleworkEligible` | Remote-job flag and telework eligibility. |
| `jobSummary` / `duties` / `requirementsSummary` | Announcement summary, duties and conditions of employment. |
| `qualificationSummary` / `education` / `evaluationCriteria` | Qualifications, education requirement and how applicants are evaluated. |
| `jobCategories` / `jobCategoryCodes` | Occupational series names and four-digit codes. |
| `dateDisplay` / `closingSoon` | Human-readable date line and the site's closing-soon badge. |
| `recordType` / `scrapedAt` | `job` and the ISO timestamp of capture. |

Fields the source does not publish for a posting are omitted; nothing is emitted as `null`, blank or a placeholder.

### How it works

The actor calls the same public search endpoint the USAJOBS website uses, then reads announcement pages for full details. No API key is needed. Requests are retried on rate limits and transient server errors, and if a datacenter address is blocked the actor automatically retries through Apify's included datacenter proxy.

### Limitations

- **USAJOBS caps a single search at 10,000 postings.** Narrow by agency, location, grade, series or keyword to reach postings beyond that ceiling.
- **Date-posted filtering is not available on the public search.** The legacy `datePostedDays` key is accepted but ignored; use `sortBy: recentlyPosted` and `maxItems` instead.
- **Full announcement text is as published.** Very long duties or qualification sections are returned whole, which makes detail-enabled runs heavier than search-only runs.
- **Grade filtering follows USAJOBS's GS-equivalent buckets.** Some pay plans (for example SV or NF) use letter grades and may not match a numeric GS range.
- **A removed or closed announcement can still appear briefly in search.** If its detail page is already gone, the core search fields are still returned and the run reports how many detail pages could not be opened.

### FAQ

**Do I need a USAJOBS API key?**
No. This actor uses the public website search and announcement pages, so it needs no API key, account, cookie or proxy setup. The old `apiKey` key is accepted but ignored.

**Can I search by GS pay grade?**
Yes. Set `gradeMin` and/or `gradeMax` (1-15). Results include every GS-equivalent grade in the range, and each record reports `payScale`, `payGradeMin` and `payGradeMax`.

**What does "Who May Apply" mean?**
It is the audience the posting is open to: public means any US citizen, competitive service means current or former federal employees, and other hiring paths cover veterans, military spouses, students, graduates, disability, overseas family members and special authorities.

**Why is a field such as `salaryMax` missing?**
Some announcements publish only a starting salary. The actor omits the missing bound rather than guessing.

**Is this affiliated with USAJOBS or the US government?**
No. This is an independent tool and is not affiliated with, endorsed by or sponsored by USAJOBS or the US Office of Personnel Management.

# Actor input Schema

## `mode` (type: `string`):

Search federal vacancies, or read full details for job links you already have.

## `keyword` (type: `string`):

Job title, skill or keyword to search for (for example "software engineer" or "data analyst").

## `locationName` (type: `string`):

City, state or country to search in, for example "Washington, DC" or "Germany".

## `department` (type: `string`):

Parent federal department name, acronym or code, for example "Department of Defense", "DOD" or "DD". Comma-separate several values.

## `agency` (type: `string`):

Agency or department name, acronym or code, for example "NASA", "Department of the Navy" or "NV27". Comma-separate several values.

## `jobCategoryCode` (type: `string`):

Four-digit federal occupational series codes, comma-separated (for example "2210" for IT or "0343" for management analysis).

## `gradeMin` (type: `integer`):

Lowest GS-equivalent grade to include (1-15).

## `gradeMax` (type: `integer`):

Highest GS-equivalent grade to include (1-15).

## `schedule` (type: `string`):

Filter by the posting's work schedule.

## `hiringPath` (type: `string`):

Filter by the audience the posting is open to.

## `securityClearance` (type: `string`):

Filter by the clearance level a posting requires.

## `jobType` (type: `string`):

Filter by appointment or job type.

## `travelPercentage` (type: `string`):

Filter by how much travel the posting requires.

## `workSite` (type: `string`):

Filter for remote jobs, exclude remote jobs, or find telework-eligible jobs.

## `relocationAssistance` (type: `boolean`):

Only return postings that reimburse relocation expenses.

## `minSalary` (type: `integer`):

Only return postings whose advertised starting salary is at least this amount.

## `sortBy` (type: `string`):

Order of returned postings.

## `includeDetails` (type: `boolean`):

Fetch each posting's full announcement for duties, qualifications, education, salary range, remote/telework status and clearance. Turn off for a faster, lighter run.

## `jobUrls` (type: `array`):

In Job Details mode, paste USAJOBS job links (https://www.usajobs.gov/job/123456789) or bare control numbers.

## `maxItems` (type: `integer`):

Maximum number of postings to return.

## Actor input object example

```json
{
  "mode": "searchJobs",
  "keyword": "software engineer",
  "schedule": "",
  "hiringPath": "",
  "securityClearance": "",
  "jobType": "",
  "travelPercentage": "",
  "workSite": "",
  "relocationAssistance": false,
  "sortBy": "",
  "includeDetails": false,
  "maxItems": 2
}
```

# Actor output Schema

## `jobs` (type: `string`):

Dataset containing every scraped federal job posting.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchJobs",
    "keyword": "software engineer",
    "includeDetails": false,
    "maxItems": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/usajobs-federal-vacancy-and-pay-grade-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchJobs",
    "keyword": "software engineer",
    "includeDetails": False,
    "maxItems": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/usajobs-federal-vacancy-and-pay-grade-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchJobs",
  "keyword": "software engineer",
  "includeDetails": false,
  "maxItems": 2
}' |
apify call dataspryva/usajobs-federal-vacancy-and-pay-grade-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/usajobs-federal-vacancy-and-pay-grade-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/O6NhNrNCvlYhdI90w/builds/CBIJjkUaFVPD5Gjej/openapi.json
