usajobs.gov 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.
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": "analyst",
"location": "Washington DC",
"results_per_page": "10"
}'Search for current job openings on USAJobs.gov using keyword and location filters. Returns paginated results with job summaries including title, agency, salary, location, and hiring paths.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of results |
| keyword | string | Search keyword (e.g., 'engineer', 'analyst', 'nurse') |
| location | string | Location name (e.g., 'Washington DC', 'New York') |
| results_per_page | integer | Number of results per page (1 to 100) |
{
"type": "object",
"fields": {
"Jobs": "array of job listing summaries 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"
},
"sample": {
"data": {
"Jobs": [
{
"Title": "General Engineer (Lead Engineer)",
"Agency": "Federal Aviation Administration",
"JobGrade": "FV",
"Location": "Hampton, Georgia",
"WorkType": "Permanent",
"Department": "Department of Transportation",
"DocumentID": "866395400",
"HiringPath": [
{
"Code": "fed-internal-search",
"Tooltip": "Jobs only open to current federal employees of the agency.",
"IsSearchFilter": false
}
],
"MinimumRange": "118206",
"WorkSchedule": "Full-time",
"SalaryDisplay": "Starting at $118,206 Per year (FV J)"
}
],
"Pager": {
"IsPaged": true,
"HasNextPage": true,
"ItemsPerPage": 25,
"NumberOfItems": 656,
"NumberOfPages": 27,
"CurrentPageIndex": 1
},
"Total": "656"
},
"status": "success"
}
}About the usajobs.gov 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.
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.
- 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 | 250 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.