# US Federal Government Jobs Search (`iocodo/us-federal-jobs`) Actor

Search current US federal government job openings through the USAJOBS Search API. Filter by keyword, location, occupational series, pay grade, salary, remote work and posting date. One clean row per opening, without agency contacts or free-text descriptions. Needs your own free USAJOBS API key.

- **URL**: https://apify.com/iocodo/us-federal-jobs.md
- **Developed by:** [IOCODO LLC](https://apify.com/iocodo) (community)
- **Categories:** Jobs
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 job openings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

### What does US Federal Government Jobs Search do?

US Federal Government Jobs Search finds current US federal government job openings and returns them in **one clean row per opening**. It reads the [USAJOBS Search API](https://developer.usajobs.gov/api-reference/get-api-search), which lists the openings of federal agencies. Give it keywords, places, occupational series, pay grades or a salary floor. You get back the title, agency, location, pay range, grade, schedule, hiring paths, remote and telework flags, closing date and the link to apply.

It works as a simple federal jobs API: no browser, no scraping. You need your own free USAJOBS API key, and the steps to get one are below.

### Why use it?

- **Job boards and career sites.** Fill a page or a feed with federal openings, filtered by series, grade, place or pay.
- **Job alerts.** Run it every day for only the openings posted in the last 24 hours and send them to a channel or a spreadsheet.
- **Labour research.** Count and compare openings by agency, occupational series, pay range, location or remote work.
- **Career planning.** Watch what an agency or a series pays and how often it hires.

On Apify you can schedule runs, call the Actor through the API, and send results to Google Sheets, Zapier, Make or a webhook.

### What data does it return?

| Field | Example |
|---|---|
| `title` | IT SPECIALIST (INFOSEC) |
| `organization`, `department` | Forest Service, Department of Agriculture |
| `positionId` | FS-26-12345678-DE |
| `url`, `applyUrl` | links to the opening and to apply |
| `locations`, `locationText` | city, state, country, latitude, longitude |
| `jobCategories` | `2210` Information Technology Management |
| `payPlanGrades`, `lowGrade`, `highGrade` | `GS`, `12`, `13` |
| `salaryMin`, `salaryMax`, `salaryInterval` | 107305, 139493, year |
| `schedule`, `appointmentType` | Full-time, Permanent |
| `whoMayApply`, `hiringPaths` | United States Citizens, `public`, `vet` |
| `telework`, `remote` | `true` or `false`, `null` when USAJOBS does not say |
| `securityClearance`, `drugTest`, `relocation`, `travel` | Secret, `false`, `false`, Occasional travel |
| `openedOn`, `closesOn` | 2026-10-19, 2026-11-02 |

Every record also carries `source`, `license`, `source_updated_at` and `retrieved_at`, so you always know where a row came from and when it was read.

**No contacts and no free text.** The output is a fixed list of fields.

- Agency contact names, e-mail addresses and phone numbers are left out.
- So are all free-text parts of the announcement: summary, duties, qualifications and how to apply. They can name people.

Open `url` on USAJOBS for the full announcement and for the instructions to apply.

### How to get your free USAJOBS API key

1. Open the [USAJOBS API request page](https://developer.usajobs.gov/apirequest/), fill in the short form and accept the USAJOBS terms.
2. USAJOBS sends the key to the e-mail address you entered.
3. Paste the key into the key field of the Actor input, and the same e-mail address into the e-mail field below it.

The key stays secret. The Actor stores it as a secret input and sends it to USAJOBS only, in the request headers. It is never written to the results, the logs or any URL.

### How to search for federal jobs

1. Open the Actor and paste your key and e-mail address.
2. Add keywords, one per line. Each keyword is a separate search. Leave the list empty to search without a keyword.
3. Narrow the search with locations, occupational series, pay grades, a minimum salary, remote work or the posting date.
4. Set **Maximum openings** and click **Start**. Download the results as JSON, CSV, Excel or HTML.

An opening that several keywords find is returned once, under the first keyword that found it. The `query` field tells you which keyword that was.

### How much does it cost?

You pay **$1 per 1,000 job openings returned** ($0.001 each). Searches that find nothing cost nothing. A run stops by itself at the maximum charge you set. The monthly credit of the free Apify plan is enough to try it. The USAJOBS key itself is free.

The Actor sends at most one request per second to USAJOBS, so a large run takes a few minutes.

### Input

See the input tab for every option. In short:

- `apiKey` and `apiEmail`: your USAJOBS key and the e-mail address it was registered with
- `keywords`: one search per keyword
- `locations`: places in the form `Atlanta, Georgia`, searched together; `radiusMiles` widens them
- `jobCategoryCodes`: four-digit occupational series such as `2210` or `0830`
- `payGradeLow` and `payGradeHigh`: grades from 1 to 15
- `minSalary`: minimum salary in dollars
- `remoteOnly` and `teleworkOnly`: keep remote or telework eligible openings
- `postedWithinDays`: only openings posted in the last 0 to 60 days
- `whoMayApply`: `all` (everything your key may see), `public` or `status`
- `maxResults`: up to 10,000 openings in total, 500 by default

### Output

Example record. The values are illustrative.

```json
{
    "query": "security",
    "positionId": "FS-26-12345678-DE",
    "title": "IT SPECIALIST (INFOSEC)",
    "organization": "Forest Service",
    "department": "Department of Agriculture",
    "url": "https://www.usajobs.gov/job/800123456",
    "applyUrl": "https://www.usajobs.gov/job/800123456?PostingChannelID=RESTAPI",
    "locations": [{ "city": "Washington, District of Columbia", "state": "District of Columbia", "country": "United States", "latitude": 38.895, "longitude": -77.0366 }],
    "locationText": "Washington, District of Columbia",
    "jobCategories": [{ "code": "2210", "name": "Information Technology Management" }],
    "payPlanGrades": ["GS"],
    "lowGrade": "12",
    "highGrade": "13",
    "promotionPotential": "13",
    "salaryMin": 107305,
    "salaryMax": 139493,
    "salaryInterval": "year",
    "salaryIntervalCode": "PA",
    "schedule": ["Full-time"],
    "appointmentType": ["Permanent"],
    "whoMayApply": "United States Citizens",
    "hiringPaths": ["public", "vet"],
    "openings": "2",
    "telework": true,
    "remote": false,
    "securityClearance": "Secret",
    "drugTest": false,
    "relocation": false,
    "travel": "Occasional travel",
    "openedOn": "2026-10-19",
    "closesOn": "2026-11-02",
    "startsOn": "2026-10-19",
    "endsOn": "2026-11-02",
    "source": { "name": "USAJOBS Search API (U.S. Office of Personnel Management)", "url": "https://developer.usajobs.gov/" },
    "license": { "name": "USAJOBS API Terms of Service (public data)", "url": "https://developer.usajobs.gov/guides/terms-of-service" },
    "source_updated_at": "2026-10-19T00:00:00.000Z",
    "retrieved_at": "2026-10-24T09:00:00.000Z"
}
```

A `SUMMARY` record in the key-value store holds:

- for each keyword, `totalAvailable` (openings USAJOBS reported) and `pushed` (openings the run returned)
- `pushed` for the whole run
- `stoppedAtLimit`, which is `true` when the run stopped at the maximum charge

### Tips

- **Daily alerts.** Schedule the Actor once a day with `postedWithinDays` set to `1`, then send the new rows to Slack, e-mail or a sheet through an Apify integration.
- **Series beat keywords.** An occupational series such as `2210` is exact. A keyword matches the words anywhere in the announcement, synonyms included.
- **Compare pay with care.** Compare `salaryMin` and `salaryMax` only between rows with the same `salaryInterval`. Hourly and yearly pay mix in one result.
- **Remote openings.** A remote opening often has no entry in `locations`. Read `locationText` instead.
- **More than 10,000 openings.** USAJOBS returns at most 10,000 rows for one search. Split the work by keyword, place or series.
- **Keep `maxResults` low** when you only need the newest rows. You pay per opening returned.
- **Check before you apply.** Dates and details can change after a run. Open `url` on USAJOBS and follow the instructions in the announcement.

### Data source and licence

- **USAJOBS Search API**, published by the U.S. Office of Personnel Management (OPM): [developer.usajobs.gov](https://developer.usajobs.gov/). Terms: [USAJOBS API Terms of Service](https://developer.usajobs.gov/guides/terms-of-service), under which the job announcement data is public data.

The Actor selects and renames fields and leaves out agency contacts and free-text descriptions; it does not change other values.

A few values change type or wording to make the rows easier to use:

- pay becomes a number
- `"True"` and `"False"` become booleans
- dates are cut to the day
- travel and clearance codes become words

The pay interval code as USAJOBS sends it stays in `salaryIntervalCode`.

This Actor is independent and is not affiliated with, endorsed by or approved by USAJOBS, the U.S. Office of Personnel Management or any federal agency.

### FAQ

#### Why do I need my own USAJOBS key?

USAJOBS gives a key to each person or organisation, and its terms do not allow sharing it.

Requesting one takes a few minutes and costs nothing. The steps are in the section on getting your key.

#### Does it return agency contacts or job descriptions?

No. Contact details and free-text descriptions are left out on purpose. The link in `url` leads to the full announcement on USAJOBS.

#### Why is `telework`, `remote` or `drugTest` empty?

The value is `null` when USAJOBS does not send that flag for the opening.

#### Why did I get fewer openings than `maxResults`?

Fewer openings matched, an opening was already returned by an earlier keyword, or the search reached the 10,000 rows USAJOBS allows for one search.

#### The run failed with a message about the key

USAJOBS refused the key or the e-mail address. Check that `apiKey` is the key USAJOBS sent you and that `apiEmail` is the e-mail address you registered it with.

#### Can I limit the search to one agency?

There is no agency filter yet. Filter the results by `organization` or `department`, or narrow the search with an occupational series and a location.

#### Found a problem?

Open an issue in the Issues tab and describe the search that went wrong. Never paste your key into an issue.

# Actor input Schema

## `apiKey` (type: `string`):

Your own USAJOBS API key. It is free: request it at https://developer.usajobs.gov/apirequest/ and USAJOBS e-mails it to you. The key is stored as a secret input and is never written to the results.

## `apiEmail` (type: `string`):

The e-mail address you gave USAJOBS when you requested the key. USAJOBS asks for it with every request.

## `keywords` (type: `array`):

One per line. Each keyword is a separate search, and an opening found by several keywords is returned once. USAJOBS looks for the words anywhere in the announcement, synonyms included. Leave empty for one search without a keyword.

## `locations` (type: `array`):

Optional. One per line, in the form USAJOBS uses: city, then state name, for example Atlanta, Georgia or Washington DC, District of Columbia. All locations are searched together. Leave empty for the whole country and abroad.

## `radiusMiles` (type: `integer`):

Optional. Also include openings within this many miles of each location. Needs at least one location.

## `jobCategoryCodes` (type: `array`):

Optional. Four-digit OPM series codes, one per line, for example 2210 (information technology management) or 0830 (mechanical engineering). Keep the leading zero.

## `payGradeLow` (type: `integer`):

Optional. Beginning grade of the jobs to find, 1 to 15. Grades follow the General Schedule; USAJOBS derives a grade from the salary for other pay plans.

## `payGradeHigh` (type: `integer`):

Optional. Ending grade of the jobs to find, 1 to 15. Use it together with the lowest grade to set a range.

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

Optional. USAJOBS works in salary bands of 25,000 dollars and applies the minimum from the start of its band, so 60,000 starts at 50,000.

## `remoteOnly` (type: `boolean`):

When on, only openings that USAJOBS marks as remote are returned.

## `teleworkOnly` (type: `boolean`):

When on, only openings marked telework eligible are kept. USAJOBS has no search filter for this, so the Actor reads more pages to fill the limit. Remote jobs are not always marked telework eligible.

## `postedWithinDays` (type: `integer`):

Optional. Only openings posted in the last 0 to 60 days. Use 1 on a daily schedule to get just the new openings.

## `whoMayApply` (type: `string`):

Which openings to search. USAJOBS gives most keys only the openings that are open to the public. The status option needs a key that USAJOBS has authorised for it.

## `maxResults` (type: `integer`):

Upper limit of openings returned in total, across all keywords. USAJOBS returns at most 10,000 rows for one search.

## Actor input object example

```json
{
  "keywords": [
    "data scientist"
  ],
  "remoteOnly": false,
  "teleworkOnly": false,
  "whoMayApply": "all",
  "maxResults": 100
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

# 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 = {
    "keywords": [
        "data scientist"
    ],
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("iocodo/us-federal-jobs").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 = {
    "keywords": ["data scientist"],
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("iocodo/us-federal-jobs").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 '{
  "keywords": [
    "data scientist"
  ],
  "maxResults": 100
}' |
apify call iocodo/us-federal-jobs --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,iocodo/us-federal-jobs"
        }
    }
}
```

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/MCxdwdMKYZVPZGbHb/builds/j9ceQfxU3ch1BxQA9/openapi.json