# USAJOBS

> Search every federal job opening on USAJOBS, the US government's official employment site: filter by keyword, title, location, agency, occupational series, pay plan, grade, salary, schedule, clearance and who may apply, read the full announcement, search the archive of 3.2 million past announcements and their text, and look up the codes federal hiring speaks in.

App · Jobs & Hiring · 20 actions. Web page: https://docs.lodol.com/docs/integrations/usajobs

## Actions

### Get historic announcement text

Read the full text an archived announcement was posted with: its summary and duties, the conditions of employment, the qualifications and education required, the documents an applicant had to send, how to apply and what happened next, the benefits, and how candidates were evaluated. Takes the same filters as the archive search: point it at one control number, or at a narrow slice; each record is large enough that a full page of 500 runs to about 10 MB.

**Inputs**

- Hiring agency (`agency_code`, text): Only include announcements posted by this organization. Most are posted by a sub-agency; a few are posted by the department itself, which is why both are listed. To match a department and everything inside it, use the Department field instead.
- Department (`department_code`, text): Only include announcements from this department, across every sub-agency inside it.
- Occupational series (`series_code`, text): Only include announcements for this occupational series: the four-digit code that says what kind of work the job is.
- Announcement number (`announcement_number`, text): Only include the announcement with this number, the one the hiring agency assigned and printed on the posting.
- USAJOBS control number (`control_number`, number): Only include the announcement with this USAJOBS control number. One at a time: the archive refuses a list. 'Search historic announcements' returns the number for every announcement it finds. From 1 to 9999999999.
- Opened on or after (`opened_on_or_after`, date): Only include announcements that opened on or after this date. Leave empty for no lower bound.
- Opened on or before (`opened_on_or_before`, date): Only include announcements that opened on or before this date. Leave empty for no upper bound.
- Closed on or after (`closed_on_or_after`, date): Only include announcements that closed on or after this date. Leave empty for no lower bound.
- Closed on or before (`closed_on_or_before`, date): Only include announcements that closed on or before this date. Leave empty for no upper bound.
- Continue from (`continuation_token`, text): The 'continuation_token' a previous run reported, to read the next 500 announcements. Keep every other filter the same as that run: the token remembers the position, not the search.

**Outputs**

- `announcements` (list): The archived announcements' full text
- `continuation_token` (text): Pass back as 'continuation_token', with the same filters, to read the next page
- `count` (number): Announcements on this page
- `has_more` (true/false): Whether a page follows
- `remaining_count` (number): How many announcements are left from this page on, this page included (not the number that matched)

**Example output**

```json
{
  "announcements": [
    {
      "announcementNumber": "DE-11600993-24-JDA",
      "benefitsURL": "http://www.secnav.navy.mil/donhr/Benefits/Pages/Default.aspx",
      "hiringAgencyCode": "NV25",
      "hiringDepartmentCode": "NV",
      "howToApply": "Interested applicants must submit resumes to the address below.",
      "howToApplyNextSteps": "Qualified applicants will be referred to the hiring manager.",
      "jobcategories": [
        {
          "series": "2210"
        }
      ],
      "majorDutiesList": "You will develop and write computer programs to search, retrieve, update and save data.",
      "positionCloseDate": "2024-02-19",
      "positionOpenDate": "2024-01-19",
      "requirementsConditionsOfEmployment": "Must be a US Citizen.",
      "requirementsQualifications": "Your resume must demonstrate at least one year of specialized experience at or equivalent to the GS-11 grade level.",
      "summary": "This is a public notice flyer to notify interested applicants of anticipated vacancies.",
      "usajobsControlNumber": 670685500
    }
  ],
  "continuation_token": "E32I1d9PVdPhzYS9H3p8sw==",
  "count": 1,
  "has_more": true,
  "remaining_count": 1352
}
```

### List agencies

Every federal hiring organization: the cabinet departments and independent agencies, and the sub-agencies inside them, each with the subelement code a job search filters on and the acronym it is known by. A sub-agency names its department in 'ParentCode' - the Naval Facilities Engineering Systems Command (NV25) sits under the Department of the Navy (NV), which in turn sits under the Department of Defense (DD).

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Agencies, each with its acronym and the department it sits under

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "AgencySubElement",
  "next_offset": null,
  "offset": 0,
  "total_count": 813,
  "values": [
    {
      "Acronym": "NAVFAC",
      "Code": "NV25",
      "IsDisabled": "No",
      "LastModified": "2020-08-13T14:12:03.19",
      "ParentCode": "NV",
      "Value": "Naval Facilities Engineering Systems Command"
    }
  ]
}
```

### List announcement closing types

How an announcement stops taking applications: on a closing date, at a closing time, at an applicant cut-off once enough have applied, or open continuously. This is what an archived announcement's closing type code means.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): The ways an announcement can close

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "AnnouncementClosingType",
  "next_offset": null,
  "offset": 0,
  "total_count": 4,
  "values": [
    {
      "Code": "01",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Closing Date"
    }
  ]
}
```

### List applicant eligibilities

The applicant eligibility categories an announcement can be limited to: United States citizens, current civil service employees, status candidates, CTAP, ICTAP and VEOA eligibles, student and internship programme eligibles, and agency employees only.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Applicant eligibility categories

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "WhoMayApply",
  "next_offset": null,
  "offset": 0,
  "total_count": 18,
  "values": [
    {
      "Code": "15514",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "United States Citizens"
    }
  ]
}
```

### List countries

The countries USAJOBS recognises, with the two-letter code each is referred to by. Federal jobs are posted in most of them, and a job's location states its country as one of these codes.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Countries, each with its USAJOBS country code

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "CountryCode",
  "next_offset": null,
  "offset": 0,
  "total_count": 258,
  "values": [
    {
      "Code": "US",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "United States"
    }
  ]
}
```

### List hiring paths

The hiring paths: who an announcement is open to. 'The public' is the one anyone may apply under; the rest are eligibilities such as veterans, military spouses, students, recent graduates, individuals with disabilities, and current federal employees in the competitive or excepted service.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Hiring paths an announcement can be open under

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "HiringPath",
  "next_offset": null,
  "offset": 0,
  "total_count": 19,
  "values": [
    {
      "Code": "PUBLIC",
      "IsDisabled": "No",
      "LastModified": "2016-02-24T15:38:19.443",
      "Value": "The public"
    }
  ]
}
```

### List locations

The geographic locations USAJOBS posts jobs in: 48,000 cities, counties, military installations and overseas posts, each with its location code, county, state and country. Use the search box: this is how to find the name USAJOBS knows a place by before filtering a job search on it.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Locations, each with its city, county, state and country

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "GeoLocCode",
  "next_offset": null,
  "offset": 0,
  "total_count": 48315,
  "values": [
    {
      "City": "Anchorage",
      "Code": "020130020",
      "Country": "US",
      "CountrySubdivision": "AK ",
      "IsDisabled": "No",
      "LastModified": "2021-09-17T14:41:22.94",
      "USCounty": "Anchorage County"
    }
  ]
}
```

### List mission-critical occupations

The occupations the federal government has flagged as mission-critical and recruits for across every agency: cyber security, data science, economics, privacy, programme and project management, grants management, STEM and intelligence.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Government-wide mission-critical occupations

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "MissionCriticalCode",
  "next_offset": null,
  "offset": 0,
  "total_count": 10,
  "values": [
    {
      "Code": "07",
      "IsDisabled": "No",
      "LastModified": "2019-04-30T14:15:18.393",
      "Value": "STEM"
    }
  ]
}
```

### List occupational series

The occupational series: the four-digit codes that say what kind of work a federal job is, from 0101 (social science) to 2210 (IT management) to 9999. These are the codes the job search and the archive filter on, and the ones an announcement's job categories are stated in.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Occupational series, with the job family each belongs to

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "OccupationalSeries",
  "next_offset": null,
  "offset": 0,
  "total_count": 822,
  "values": [
    {
      "Code": "2210",
      "IsDisabled": "No",
      "JobFamily": "2200",
      "LastModified": "2016-03-04T10:57:35.75",
      "Value": "Information Technology Management"
    }
  ]
}
```

### List pay intervals

How a salary is quoted: per year, per hour, per day, per month, bi-weekly, per school year, as a student stipend, on a fee basis, piece work, or without compensation. This is the rate interval code on a job's pay range, and reading it is what stops an hourly rate being compared with an annual one.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): The intervals a salary can be quoted over

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "RemunerationRateIntervalCode",
  "next_offset": null,
  "offset": 0,
  "total_count": 10,
  "values": [
    {
      "Code": "PA",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Per Year"
    }
  ]
}
```

### List pay plans

The federal pay plans: GS for the General Schedule most white-collar jobs sit on, WG for wage-grade trades, ES for the Senior Executive Service, and several hundred more. This is the code the job search calls a job grade code, and the one an archived announcement states as its pay scale.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Pay plans, each with the kind of position it covers

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "PayPlans",
  "next_offset": null,
  "offset": 0,
  "total_count": 391,
  "values": [
    {
      "Code": "GS",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "General Schedule"
    }
  ]
}
```

### List required documents

The standard documents an application can be asked for: a resume, transcripts, an SF-50, a DD-214, a VA letter, an SF-15, performance appraisals, licences and the rest. These are the documents an announcement's required-documents list names.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Standard documents an application can require

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "RequiredStandardDocuments",
  "next_offset": null,
  "offset": 0,
  "total_count": 34,
  "values": [
    {
      "Code": "16751",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Resume"
    }
  ]
}
```

### List security clearances

The security clearance levels a federal position can require, from none through Confidential, Secret and Top Secret to Sensitive Compartmented Information and the Department of Energy's Q and L authorizations.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Security clearance levels a job can require

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "SecurityClearance",
  "next_offset": null,
  "offset": 0,
  "total_count": 10,
  "values": [
    {
      "Code": "2",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Secret"
    }
  ]
}
```

### List service types

The three federal services a position can sit in: the competitive service, the excepted service, and the Senior Executive Service. This decides which hiring rules apply and which candidates an agency may consider.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Federal service types a position can sit in

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "ServiceType",
  "next_offset": null,
  "offset": 0,
  "total_count": 3,
  "values": [
    {
      "Code": "01",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Competitive"
    }
  ]
}
```

### List states and provinces

The subdivisions of every country USAJOBS posts in: the fifty US states, the District of Columbia and the territories, plus the provinces and regions of everywhere else. Each names the country it belongs to, so a job's state can be resolved to a country without guessing.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Country subdivisions, each with the country it belongs to

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "CountrySubdivisionCode",
  "next_offset": null,
  "offset": 0,
  "total_count": 2309,
  "values": [
    {
      "Code": "AK",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "ParentCode": "US",
      "Value": "Alaska"
    }
  ]
}
```

### List travel requirements

How much travel a position requires, as the bands USAJOBS publishes them in: none, occasional, 25% or less, 50% or less, 75% or less, or 76% and above.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Travel requirement bands a job can carry

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "TravelPercentage",
  "next_offset": null,
  "offset": 0,
  "total_count": 7,
  "values": [
    {
      "Code": "1",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Occasional travel"
    }
  ]
}
```

### List work schedules

The position schedule types: full-time, part-time, shift work, intermittent, job sharing, or multiple schedules. This is the code a job's schedule is reported under, and the one the schedule filter on a job search takes.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Work schedules a job can be posted under

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "PositionScheduleType",
  "next_offset": null,
  "offset": 0,
  "total_count": 6,
  "values": [
    {
      "Code": "1",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Full-time"
    }
  ]
}
```

### List work types

The position offering types, which USAJOBS calls work types: permanent, temporary, term, detail, seasonal, summer, internship, telework and the rest. This is what says whether a job is a career or a season.

**Inputs**

- Search (`search`, text): Only return values whose code, name or any other detail contains this text. Leave empty for the whole list.
- Include retired values (`include_retired`, true/false): Turn on to include codes USAJOBS has withdrawn. An archived announcement can still carry one; a new search will never match one. Default: `false`.
- Number of values (`limit`, number): How many values to return, 1-1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Skip (`offset`, number): How many values to skip before the first one returned; use the 'next_offset' from a previous run to read the next page. Defaults to 0. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): Values on this page
- `date_generated` (text): When USAJOBS built this copy of the list
- `has_more` (true/false): Whether a page follows
- `limit` (number): Page size used
- `list_id` (text): USAJOBS' own name for this code list
- `next_offset` (number): The 'offset' that reads the next page
- `offset` (number): Values skipped
- `total_count` (number): Values matching the search, across every page
- `values` (list): Position offering types a job can be posted as

**Example output**

```json
{
  "count": 1,
  "date_generated": "2026-08-27T20:06:54.602126Z",
  "has_more": false,
  "limit": 100,
  "list_id": "PositionOfferingType",
  "next_offset": null,
  "offset": 0,
  "total_count": 15,
  "values": [
    {
      "Code": "15317",
      "IsDisabled": "No",
      "LastModified": "2011-07-07T13:49:34.73",
      "Value": "Permanent"
    }
  ]
}
```

### Search historic announcements

Search the archive of every job announcement USAJOBS has ever posted, closed ones included (3.2 million of them). Returns each announcement's title, agency and department, grade range and salary, appointment type and schedule, service type, clearance, travel and telework, who it was open to, its occupational series and locations, and the dates it opened and closed. Five hundred to a page; feed the 'continuation_token' back in, with the same filters, to read the next one.

**Inputs**

- Hiring agency (`agency_code`, text): Only include announcements posted by this organization. Most are posted by a sub-agency; a few are posted by the department itself, which is why both are listed. To match a department and everything inside it, use the Department field instead.
- Department (`department_code`, text): Only include announcements from this department, across every sub-agency inside it.
- Occupational series (`series_code`, text): Only include announcements for this occupational series: the four-digit code that says what kind of work the job is.
- Announcement number (`announcement_number`, text): Only include the announcement with this number, the one the hiring agency assigned and printed on the posting.
- USAJOBS control number (`control_number`, number): Only include the announcement with this USAJOBS control number. One at a time: the archive refuses a list. 'Search historic announcements' returns the number for every announcement it finds. From 1 to 9999999999.
- Opened on or after (`opened_on_or_after`, date): Only include announcements that opened on or after this date. Leave empty for no lower bound.
- Opened on or before (`opened_on_or_before`, date): Only include announcements that opened on or before this date. Leave empty for no upper bound.
- Closed on or after (`closed_on_or_after`, date): Only include announcements that closed on or after this date. Leave empty for no lower bound.
- Closed on or before (`closed_on_or_before`, date): Only include announcements that closed on or before this date. Leave empty for no upper bound.
- Continue from (`continuation_token`, text): The 'continuation_token' a previous run reported, to read the next 500 announcements. Keep every other filter the same as that run: the token remembers the position, not the search.

**Outputs**

- `announcements` (list): Archived announcements, newest control number first
- `continuation_token` (text): Pass back as 'continuation_token', with the same filters, to read the next page
- `count` (number): Announcements on this page
- `has_more` (true/false): Whether a page follows
- `remaining_count` (number): How many announcements are left from this page on, this page included (not the number that matched)

**Example output**

```json
{
  "announcements": [
    {
      "announcementClosingTypeCode": "01",
      "announcementClosingTypeDescription": "Closing Date",
      "announcementNumber": "DE-11600993-24-JDA",
      "appointmentType": "Permanent",
      "hiringAgencyCode": "NV25",
      "hiringAgencyName": "Naval Facilities Engineering Systems Command",
      "hiringDepartmentCode": "NV",
      "hiringDepartmentName": "Department of the Navy",
      "hiringpaths": [
        {
          "hiringPath": "The public"
        }
      ],
      "jobcategories": [
        {
          "series": "2210"
        }
      ],
      "maximumGrade": "12",
      "maximumSalary": 114634.0,
      "minimumGrade": "12",
      "minimumSalary": 88183.0,
      "payScale": "GS",
      "positionCloseDate": "2024-02-19",
      "positionOpenDate": "2024-01-19",
      "positionOpeningStatus": "Job closed",
      "positionTitle": "IT SPECIALIST (SYSANALYSIS)",
      "positionlocations": [
        {
          "positionLocationCity": "Naval Facilities Engineering Command, Atlantic",
          "positionLocationCountry": "United States",
          "positionLocationState": "Virginia"
        }
      ],
      "promotionPotential": "None",
      "salaryType": "Per Year",
      "securityClearance": "Secret",
      "securityClearanceRequired": "Y",
      "serviceType": "Competitive",
      "supervisoryStatus": "N",
      "teleworkEligible": "N",
      "travelRequirement": "Occasional travel",
      "usajobsControlNumber": 670685500,
      "workSchedule": "Full-time"
    }
  ],
  "continuation_token": "E32I1d9PVdPhzYS9H3p8sw==",
  "count": 1,
  "has_more": true,
  "remaining_count": 1352
}
```

### Search jobs

Search every federal job opening posted on USAJOBS right now. Filter by keyword, title, location and radius, agency, occupational series, pay plan, grade, salary, work type and schedule, security clearance, travel, who may apply, whether it is remote, and how recently it was posted. Returns each job with its announcement number, links to view and apply, locations and coordinates, pay range, opening and closing dates, and the full announcement text. With no filters at all this is the whole board.

**Inputs**

- Keyword (`keyword`, text): Words to look for anywhere in the announcement: the title, the duties, the qualifications. Synonyms are matched too, so 'attorney' also finds 'lawyer'.
- Job title contains (`position_title`, text): Only match jobs whose title contains this text. Narrower than Keyword, which searches the whole announcement.
- Locations (`location_names`, list): Cities, states, countries or military installations to search in. Add several to search all of them. 'List locations' looks up the name USAJOBS knows a place by.
- Radius (miles) (`radius`, number): Also match jobs this many miles from the locations above. Leave empty to match only the locations themselves. From 1 to 6000.
- Agencies (`organization_codes`, list): Only match jobs at these agencies. Pick a whole department or one of its sub-agencies; choosing several matches any of them.
- Occupational series (`series_codes`, list): Only match jobs in these occupational series: the four-digit codes that say what kind of work a job is.
- Pay plans (`pay_plan_codes`, list): Only match jobs paid under these pay plans. GS is the General Schedule most white-collar federal jobs sit on.
- Open to (`hiring_paths`, list): Only match jobs open to these groups. 'The public' is the one anyone can apply for; the rest need the eligibility named. One or more of: `public` (The public), `vet` (Veterans), `nguard` (National Guard & Reserves), `disability` (Individuals with disabilities), `native` (Native Americans), `mspouse` (Military spouses), `student` (Students), `graduates` (Recent graduates), `ses` (Senior executives), `peace` (Peace Corps & AmeriCorps VISTA), and 7 more.
- Work types (`work_types`, list): Only match jobs of these types: permanent, term, seasonal, internship and the rest. USAJOBS calls this 'work type'. One or more of: `15317` (Permanent), `15318` (Temporary), `15319` (Term), `15320` (Detail), `15321` (Temporary promotion), `15322` (Seasonal), `15323` (Summer), `15326` (Recent graduates), `15327` (Multiple), `15328` (Internships), and 4 more.
- Work schedules (`work_schedules`, list): Only match jobs on these schedules, such as full-time. One or more of: `1` (Full-time), `2` (Part-time), `3` (Shift work), `4` (Intermittent), `5` (Job sharing), `6` (Multiple schedules).
- Security clearance (`security_clearances`, list): Only match jobs requiring these clearance levels. Choose 'Not required' for jobs that need none. One or more of: `0` (Not required), `1` (Confidential), `2` (Secret), `3` (Top Secret), `4` (Sensitive Compartmented Information), `5` (Q Access Authorization), `7` (L Access Authorization), `8` (Other).
- Travel required (`travel_percentages`, list): Only match jobs with these travel requirements. One or more of: `0` (None), `1` (Occasional travel), `2` (25% or less), `5` (50% or less), `7` (75% or less), `8` (76% or greater).
- Mission-critical occupations (`mission_critical_tags`, list): Only match jobs the government has flagged as mission-critical, such as STEM or cyber security. One or more of: `Cyber Security`, `Data Scientist`, `Economist`, `Privacy`, `Program/Project Management` (Program & project management), `Grants Management`, `STEM`, `Intelligence`.
- Who may apply (`who_may_apply`, text): Which announcements to search. Leave empty for the public ones, which is what an ordinary API key can see; the other two need a key OPM has authorised for status jobs. One of: `Public` (Open to the public), `Status` (Open to federal employees and other status candidates), `All` (Both).
- Minimum salary (`minimum_salary`, number): Only match jobs paying at least this much a year, in dollars. USAJOBS rounds to its own salary bands, so $15,500 matches the $0-$24,999 band. From 0 to 1000000.
- Maximum salary (`maximum_salary`, number): Only match jobs paying at most this much a year, in dollars. Rounded to the same salary bands as the minimum. From 0 to 1000000.
- Lowest grade (`pay_grade_low`, number): Only match jobs starting at this General Schedule grade or above, 1 to 15. From 1 to 15.
- Highest grade (`pay_grade_high`, number): Only match jobs topping out at this General Schedule grade or below, 1 to 15. From 1 to 15.
- Remote jobs only (`remote_only`, true/false): Turn on for remote jobs only. Leave off to include both remote and on-site jobs.
- Relocation paid only (`relocation_offered`, true/false): Turn on for jobs that reimburse relocation expenses. Leave off to include jobs that do not.
- Posted within (days) (`posted_within_days`, number): Only match jobs posted in the last this many days, 0-60. This is the filter a scheduled workflow uses to see only what is new. From 0 to 60.
- How much detail (`field_set`, text): 'Full announcement' includes the duties, requirements, benefits and how to apply. 'Summary only' returns a fraction of that, which is quicker when the step only needs titles and links. One of: `Full` (Full announcement), `Min` (Summary only).
- Sort by (`sort_field`, text): What to order the results by. Leave empty for the search's own relevance ranking. One of: `opendate` (Date opened), `closedate` (Date closing), `jobtitle` (Job title), `positiontitle` (Position title), `organizationname` (Organization), `agency`, `department`, `location`, `salary`, `salarymin` (Minimum salary), `honame` (Hiring office).
- Sort direction (`sort_direction`, text): Which way to order the sort chosen above. One of: `Asc` (Ascending (lowest or earliest first)), `desc` (Descending (highest or latest first)).
- Jobs per page (`results_per_page`, number): How many jobs to return, 1-500. Defaults to 25. From 1 to 500. Default: `25`.
- Page (`page`, number): Which page of results to return, counting from 1. Use the 'next_page' a previous run reported. USAJOBS returns at most 10,000 jobs for one search, however it is paged. From 1 to 10000. Default: `1`.

**Outputs**

- `count` (number): Jobs on this page
- `has_more` (true/false): Whether a page follows
- `jobs` (list): Job openings, each with its announcement under 'MatchedObjectDescriptor'
- `next_page` (number): The 'page' that reads the next page
- `page` (number): The page returned
- `page_count` (number): How many pages USAJOBS says the search has
- `refiners` (object): How the matches break down by agency, grade, salary, work type, schedule and series
- `results_per_page` (number): Page size used
- `total_count` (number): Jobs matching the search, across every page

**Example output**

```json
{
  "count": 1,
  "has_more": true,
  "jobs": [
    {
      "MatchedObjectDescriptor": {
        "ApplicationCloseDate": "2026-12-01T00:00:00Z",
        "ApplyURI": [
          "https://www.usajobs.gov/GetJob/ViewDetails/21947200"
        ],
        "DepartmentName": "Department of the Navy",
        "JobCategory": [
          {
            "Code": "2210",
            "Name": "Information Technology Management"
          }
        ],
        "JobGrade": [
          {
            "Code": "GS"
          }
        ],
        "OrganizationName": "Space and Naval Warfare Systems Command",
        "PositionEndDate": "2026-12-01T00:00:00Z",
        "PositionID": "SW62210-05-1716110PB411413H",
        "PositionLocation": [
          {
            "CityName": "Point Loma Complex, San Diego, California",
            "CountryCode": "United States",
            "CountrySubDivisionCode": "California",
            "Latitude": 32.7042961,
            "LocationName": "Point Loma Complex, San Diego, California",
            "Longitude": -117.194382
          }
        ],
        "PositionLocationDisplay": "Point Loma Complex, San Diego, California",
        "PositionOfferingType": [
          {
            "Code": "15317",
            "Name": "Permanent"
          }
        ],
        "PositionRemuneration": [
          {
            "Description": "Per Year",
            "MaximumRange": "119746",
            "MinimumRange": "92108",
            "RateIntervalCode": "PA"
          }
        ],
        "PositionSchedule": [
          {
            "Code": "1",
            "Name": "Full Time"
          }
        ],
        "PositionStartDate": "2026-06-05T00:00:00Z",
        "PositionTitle": "IT SPECIALIST (INFOSEC/NETWORK)",
        "PositionURI": "https://www.usajobs.gov/GetJob/ViewDetails/21947200",
        "PublicationStartDate": "2026-06-05T00:00:00Z",
        "UserArea": {
          "Details": {
            "HighGrade": "13",
            "JobSummary": "Serve as an information security specialist.",
            "LowGrade": "12",
            "OrganizationCodes": "DD/NV/NV39",
            "SubAgencyName": "Naval Information Warfare Center Pacific",
            "WhoMayApply": {
              "Code": "15514",
              "Name": "United States Citizens"
            }
          },
          "IsRadialSearch": false
        }
      },
      "MatchedObjectId": "21947200",
      "RelevanceRank": 0.0
    }
  ],
  "next_page": 2,
  "page": 1,
  "page_count": 33,
  "refiners": {
    "GradeBucket": [
      {
        "RefinementCount": "46",
        "RefinementName": "12",
        "RefinementToken": "^12$",
        "RefinementValue": "12"
      }
    ],
    "Organization": [
      {
        "RefinementCount": "12",
        "RefinementName": "DD/NV/NV39",
        "RefinementToken": "^DD/NV/NV39$",
        "RefinementValue": "DD/NV/NV39"
      }
    ]
  },
  "results_per_page": 25,
  "total_count": 812
}
```