> ## Documentation Index > Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt > Use this file to discover all available pages before exploring further. # Historical > Get US labor market history since 1939: nonfarm payrolls, the unemployment rate, participation, hourly earnings, job openings, hires, quits, and weekly jobless claims, with the change from the prior period and from a year earlier. ### Overview The Labor Market API lets you pull one US labor market series at a time: the jobs report (nonfarm payrolls, the unemployment rate, participation, hourly earnings), JOLTS job openings, hires, and quits, and weekly jobless claims. Monthly series run from 1939 and weekly claims from 1967, with the change from the prior period and from a year earlier computed for you. We source the data directly from authoritative government sources. Values are in each series' own units (thousands of persons, percent, dollars per hour, persons); the changes are in the same units, plus a percent change over the year. To get started, please create an account and grab your API key at [financialdatasets.ai](https://financialdatasets.ai). You will use the API key to authenticate your API requests. ### Coverage | History | Series | Updated | | ------------- | ------ | ------------------ | | 1939 to today | 24 | Monthly and weekly | ### Series Every concept is available seasonally adjusted (`_sa`) and, except the 4-week averages, not seasonally adjusted (`_nsa`). Monthly (`date` is the first day of the month): | Series | What it is | Units | From | | ----------------------------------------------------- | ------------------------------------------------------------------------ | -------------------- | ---- | | `payrolls_sa`, `payrolls_nsa` | Total nonfarm employment | Thousands of persons | 1939 | | `unemployment_rate_sa`, `unemployment_rate_nsa` | Unemployment rate | Percent | 1948 | | `unemployment_rate_u6_sa`, `unemployment_rate_u6_nsa` | U-6: unemployed, marginally attached, and part time for economic reasons | Percent | 1994 | | `participation_rate_sa`, `participation_rate_nsa` | Labor force participation rate | Percent | 1948 | | `hourly_earnings_sa`, `hourly_earnings_nsa` | Average hourly earnings, all private employees | Dollars per hour | 2006 | | `job_openings_sa`, `job_openings_nsa` | Job openings, total nonfarm | Thousands | 2000 | | `hires_sa`, `hires_nsa` | Hires, total nonfarm | Thousands | 2000 | | `quits_sa`, `quits_nsa` | Quits, total nonfarm | Thousands | 2000 | Weekly (`date` is the week-ending Saturday): | Series | What it is | Units | From | | --------------------------------------------------------------- | ----------------------------------------------- | ------- | ---- | | `initial_claims_sa`, `initial_claims_nsa` | Initial jobless claims | Persons | 1967 | | `initial_claims_4_week_sa` | Initial jobless claims, 4-week moving average | Persons | 1967 | | `continued_claims_sa`, `continued_claims_nsa` | Continued jobless claims | Persons | 1967 | | `continued_claims_4_week_sa` | Continued jobless claims, 4-week moving average | Persons | 1967 | | `insured_unemployment_rate_sa`, `insured_unemployment_rate_nsa` | Insured unemployment rate | Percent | 1971 | You can fetch this list, with each series' frequency and first available date, with a free `GET` request to: [https://api.financialdatasets.ai/macro/labor/series/](https://api.financialdatasets.ai/macro/labor/series/) ### Reading the fields * `date` is the reference period, not the release date: the first day of the month for monthly series (`2026-08-01` is the August 2026 jobs report, published in early September) and the week-ending Saturday for weekly series (`2026-09-19` is the week of September 13 to 19). * `value` is the published figure in the series' units. * `change_prior` is `value` minus the prior period's value: the prior month for monthly series, the prior week for weekly. Same units as `value`. * `change_year` is `value` minus the value one year earlier: the same month a year back, or the week 52 weeks back. Same units as `value`. * `change_year_pct` is `change_year` as a percent of the year-earlier value, rounded to one decimal. It is `null` for series measured in percent (the unemployment, participation, and insured unemployment rates): a rate's change is stated in points, in `change_year`. * A change is `null` when the comparison period was not published. * History is the latest published values. When a past period is revised, the stored value is replaced. The newest week of a weekly series is the advance figure; it is replaced by the final figure when that is published. ### Getting Started There are only 3 steps for making a successful API call: 1. Add your API key to the header of the request as `X-API-KEY`. 2. Add the `series` parameter, which is required. Optionally add `start_date` and `end_date` (inclusive, `YYYY-MM-DD`). For a monthly series any day inside a month selects that month; for a weekly series you get every week-ending Saturday inside the window. With no dates you get the trailing five years. 3. Execute the API request. Rows come newest first in pages of up to 10. When more rows remain, the response includes a `next_page_url`; request it as-is to get the next page. See the [pagination guide](/guides/pagination). ### Example ```python Labor Market theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import requests # add your API key to the headers headers = { "X-API-KEY": "your_api_key_here" } # set parameters series = 'payrolls_sa' # required start_date = '2025-09-01' # optional end_date = '2026-08-31' # optional # create the URL with parameters url = ( f'https://api.financialdatasets.ai/macro/labor' f'?series={series}' f'&start_date={start_date}' f'&end_date={end_date}' ) # make API request response = requests.get(url, headers=headers) # parse the observations from the response labor = response.json().get('labor') ``` ### Example Response ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "labor": [ { "series": "payrolls_sa", "date": "2026-08-01", "value": 159075, "change_prior": 162, "change_year": 603, "change_year_pct": 0.4 } ] } ``` ## OpenAPI ````yaml GET /macro/labor openapi: 3.0.1 info: title: Financial Datasets API description: >- Stock market API with real-time and historical financial data for 27,000+ tickers over 30+ years. Financial statements, equity prices, insider trades, SEC filings, and more. version: 1.0.0 license: name: MIT url: https://opensource.org/licenses/MIT contact: name: API Support url: mailto:support@financialdatasets.ai email: support@financialdatasets.ai termsOfService: https://financialdatasets.ai/terms-of-use servers: - url: https://api.financialdatasets.ai/ description: Production server security: - X-API-KEY: [] tags: - name: Financial Statements description: Access to income statements, balance sheets, and cash flow statements - name: Market Data description: Real-time and historical price data - name: Company Information description: Company facts like ticker, name, and description - name: Earnings description: Earnings data and related information - name: News description: Real-time and historical news articles - name: SEC Filings description: SEC filings and regulatory documents - name: Insider Trades description: Insider trading activity and transactions - name: Activist Ownership description: Activist stakes from SEC Schedule 13D filings, in real time - name: Beneficial Ownership description: >- Holders of more than 5% of a company's shares, from SEC Schedules 13D and 13G - name: Insider Ownership description: Insider ownership statements from SEC Forms 3 and 5 - name: Institutional Holdings description: SEC-direct 13F equity holdings of institutional investment managers - name: IPOs description: >- Upcoming IPOs from SEC registration statements (Form S-1), with extracted pre-IPO financial statements - name: Index Funds description: >- ETF and index-fund holdings, weights, and the funds that hold a given security - name: Financial Metrics description: Financial ratios, metrics, and key performance indicators - name: Macroeconomics description: Real-time and historical macroeconomic data like interest rates - name: KPIs description: Sector-specific operational KPIs extracted from earnings releases. - name: Agent Account description: Self-serve account creation and funding for AI agents. paths: /macro/labor: get: tags: - Macroeconomics summary: Labor Market (Historical) description: >- US labor market history for one series (the jobs report: nonfarm payrolls, unemployment rate, participation, hourly earnings; JOLTS job openings, hires, quits; weekly jobless claims), newest first, with the change from the prior period and from a year earlier. Dates are reference periods: the first day of the month for monthly series, the week-ending Saturday for weekly series. Values are in the series' units, sourced from authoritative government sources. A change is null when the comparison period was not published; change_year_pct is null for series measured in percent. operationId: getLabor parameters: - name: series in: query description: >- The series id, e.g. payrolls_sa. Eight monthly concepts (payrolls, unemployment_rate, unemployment_rate_u6, participation_rate, hourly_earnings, job_openings, hires, quits) and five weekly ones (initial_claims, initial_claims_4_week, continued_claims, continued_claims_4_week, insured_unemployment_rate), each seasonally adjusted (_sa) and, except the 4-week averages, not (_nsa). Use the /macro/labor/series endpoint to get the list. required: true schema: type: string - name: start_date in: query description: >- The first period to return, inclusive, in YYYY-MM-DD format; for a monthly series any day inside a month selects that month. Defaults to five years before end_date when both dates are omitted; omit it with an end_date to get all available history through that date. required: false schema: type: string - name: end_date in: query description: >- The last period to return, inclusive, in YYYY-MM-DD format. Defaults to today. required: false schema: type: string - name: cursor in: query description: >- Opaque pagination cursor from a previous response's next_page_url. When provided, all other query parameters are ignored: the cursor carries the original request's filters. Treat it as opaque; do not construct or modify it. required: false schema: type: string responses: '200': description: Labor market response content: application/json: schema: $ref: '#/components/schemas/LaborResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' components: schemas: LaborResponse: type: object properties: labor: type: array items: $ref: '#/components/schemas/LaborObservation' next_page_url: type: string description: >- Absolute URL of the next page of results. Present only when more results remain; request it as-is to continue. Each page holds up to 10 records. LaborObservation: type: object properties: series: type: string description: The series id, e.g. payrolls_sa. date: type: string description: >- The reference period in YYYY-MM-DD format: the first day of the month for monthly series (2026-08-01 for August 2026), the week-ending Saturday for weekly series. Not the release date. value: type: number nullable: true description: >- The published figure in the series' units (thousands of persons, percent, dollars per hour, persons). Null when the period was not published. change_prior: type: number nullable: true description: >- value minus the prior period's value (prior month or prior week), in the same units. Null when either period was not published. change_year: type: number nullable: true description: >- value minus the value one year earlier (the same month a year back, or the week 52 weeks back), in the same units. Null when either period was not published. change_year_pct: type: number nullable: true description: >- change_year as a percent of the year-earlier value, rounded to one decimal. Null when either period was not published, and always null for series measured in percent, whose change is stated in points in change_year. ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. responses: BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Bad Request message: Invalid request parameters UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized message: Invalid API key provided PaymentRequiredError: description: The request requires a paid subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Payment Required message: >- This endpoint requires a paid subscription. Please upgrade your plan. NotFoundError: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Not Found message: Ticker XXXX not found securitySchemes: X-API-KEY: type: apiKey name: X-API-KEY description: API key for authentication. in: header ````