USAJobs APIusajobs.gov ↗
Search federal job openings, retrieve full announcement details, access historic JOAs, and fetch reference code lists from USAJobs.gov via a single API.
What is the USAJobs API?
This API exposes 4 endpoints covering the full breadth of USAJobs.gov data: active job search, detailed announcement retrieval, historic Job Opportunity Announcements, and reference code lists. The search_jobs endpoint returns paginated results with up to 100 jobs per page, each including title, agency, salary, location, work schedule, and hiring paths. The get_job_detail endpoint delivers both structured metadata and the full announcement text — duties, qualifications, and how-to-apply instructions — for any given control number.
curl -X POST 'https://api.parse.bot/scraper/345ec21c-b44c-4c8a-8957-ba2ed520e065/search_jobs' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "1",
"keyword": "engineer",
"location": "Washington DC",
"results_per_page": "5"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace usajobs-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""USAJobs.gov API — search federal jobs, drill into details, browse reference codes."""
from parse_apis.usajobs.gov_api import USAJobs, CodeListName, JobNotFound
client = USAJobs()
# Search for engineering jobs in Washington DC
for job in client.jobs.search(keyword="engineer", location="Washington DC", limit=3):
print(job.title, "|", job.agency, "|", job.salary_display)
# Drill into the first result's full details
job = client.jobs.search(keyword="nurse", limit=1).first()
if job:
detail = job.details()
print(detail.position_title, detail.hiring_agency_name, detail.minimum_salary)
# Fetch historic JOAs by control number
for joa in client.historicjoas.list(control_numbers="870839500", limit=3):
print(joa.position_title, joa.hiring_agency_name, joa.position_close_date)
# Browse hiring path reference codes
for entry in client.codeentries.list(list_name=CodeListName.HIRING_PATHS, limit=5):
print(entry.code, entry.value)
# Typed error handling — catch when a job isn't found
try:
missing = client.job(document_id="000000000").details()
print(missing.position_title)
except JobNotFound as exc:
print(f"Job not found: {exc.control_number}")
print("exercised: jobs.search / job.details / historicjoas.list / codeentries.list")
Search for current federal job openings on USAJobs.gov. Supports keyword and location filters with paginated results. Each result includes job title, agency, salary, location, work schedule, and hiring paths. Returns up to 100 results per page.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of results (1-based) |
| keyword | string | Search keyword to match against job titles and descriptions (e.g., 'engineer', 'analyst', 'nurse') |
| location | string | Location name to filter results (e.g., 'Washington DC', 'New York', 'Texas') |
| results_per_page | integer | Number of results per page (1 to 100) |
{
"type": "object",
"fields": {
"Jobs": "array of job listing objects with Title, Agency, Department, SalaryDisplay, DocumentID, Location, WorkSchedule, WorkType, HiringPath, JobGrade, and other fields",
"Pager": "object containing pagination metadata including NumberOfPages, NumberOfItems, CurrentPageIndex, HasNextPage",
"Total": "string representing total number of matching results"
}
}About the USAJobs API
Searching Active Federal Jobs
The search_jobs endpoint accepts a keyword string (e.g., engineer, nurse), a location string, a page index, and a results_per_page count between 1 and 100. Each result in the Jobs array includes Title, Agency, Department, SalaryDisplay, DocumentID, Location, WorkSchedule, WorkType, and Hiring path flags. The Pager object tells you NumberOfPages, NumberOfItems, CurrentPageIndex, and HasNextPage, so you can iterate through large result sets reliably. The Total field gives you the raw count of matching announcements.
Retrieving Full Announcement Details
Pass any DocumentID from search results as the control_number parameter to get_job_detail. The response splits into two top-level objects: metadata (structured fields like positionTitle, hiringAgencyName, salary range, locations array, work schedule, and hiring paths) and announcement_text (free-form sections including summary, duties, qualifications, education requirements, how to apply, and benefits). This split makes it straightforward to index structured fields separately from full-text content.
Historic Job Opportunity Announcements
The get_historic_joas endpoint supports bulk retrieval of past announcements. At least one filter is required: agency_code (e.g., CM for Commerce, AF for Air Force), a comma-separated list of control_numbers, or date range pairs using start_open_date/end_open_date and start_close_date/end_close_date (all in YYYY-MM-DD format). Results are paginated using a continuationToken from the paging object alongside totalCount and pageSize.
Reference Code Lists
The get_codelist endpoint accepts a list_name parameter with four accepted values: occupationalseries, agencysubelements, payplans, and hiringpath. Each response includes a CodeList array containing a ValidValue array of entries with Code, Value, and LastModified fields, plus a top-level DateGenerated ISO timestamp. These lists are useful for translating codes found in job metadata back to human-readable labels, or for building filter UIs.
The USAJobs API is a managed, monitored endpoint for usajobs.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when usajobs.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official usajobs.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate all open federal engineering roles by keyword and location for a job board targeting government contractors
- Pull full announcement text from
get_job_detailto build a full-text search index of federal job duties and qualifications - Track hiring trends across agencies using
get_historic_joasfiltered byagency_codeand date ranges - Map occupational series codes from job metadata to descriptive titles using the
occupationalseriescode list - Monitor new postings for a specific agency by polling
search_jobswith an agency keyword and comparingDocumentIDvalues - Build a salary benchmarking dataset for federal positions by collecting
SalaryDisplayacross historic JOAs - Translate
hiringpathcodes in search results to plain-English labels using thehiringpathcode list
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USAJobs.gov have an official developer API?+
What does `get_historic_joas` return that `search_jobs` does not?+
search_jobs only surfaces currently active announcements. get_historic_joas returns closed and expired Job Opportunity Announcements, filterable by agency_code, open/close date ranges, or specific control_numbers. Its paging object uses a continuationToken rather than a page index, which is important to handle correctly when iterating large bulk retrievals.Can I filter `search_jobs` results by occupational series or pay grade?+
search_jobs endpoint currently accepts keyword, location, page, and results_per_page as filters. Filtering by occupational series code or pay grade is not directly exposed as a parameter. You can use get_codelist with list_name=occupationalseries to retrieve series codes and then apply post-retrieval filtering in your own code, or fork this API on Parse and revise it to add those filter parameters.Does the API return application status or user profile data from USAJobs accounts?+
How fresh is the job listing data returned by `search_jobs`?+
get_job_detail. Always check the close date fields in metadata before acting on a result.