BLS footnote codes are per-survey, and "value" can be a dash
Checked 2026-09-08 · Vintages and revisions
In a BLS API response, value is always a string and is sometimes the single character "-", meaning no figure was published for that period. The reason sits in the same row's footnotes array as a code, and the code table is per-survey and not shared: code 9 in the household survey means the 2025 appropriations lapse, and there is no code 9 in the payroll survey at all. Look the code up in that survey's own footnote file or you will translate it into the wrong sentence.
What we saw
October 2025 in the unemployment rate series has value "-" with an explanatory footnote, sitting between two ordinary numeric months. Source (Results.series[0].data, year 2025 period M10, 2026-09-08).
{"year":"2025","period":"M11","periodName":"November","value":"4.5","footnotes":[{}]},{"year":"2025","period":"M10","periodName":"October","value":"-","footnotes":[{"code":"9","text":"Data unavailable due to the 2025 lapse in appropriations."}]},{"year":"2025","period":"M09","periodName":"September","value":"4.4","footnotes":[{}]}An ordinary row still carries a footnotes array - it holds one empty object. The array is never absent, so testing for its presence tells you nothing; test whether footnotes[0] has a code key. Source (Results.series[0].data[].footnotes, 2026-09-08).
"value":"4.4","footnotes":[{}]A revision is announced the same way. January 2026 carries code 12 saying the estimates were revised for updated population controls - the only in-band signal that this month is not the month you fetched last time. Source (Results.series[0].data, year 2026 period M01, 2026-09-08).
{"year":"2026","period":"M01","periodName":"January","value":"4.3","footnotes":[{"code":"12","text":"January 2026 estimates were revised to incorporate updated population controls. For more information, see www.bls.gov/cps/documentation.htm#pop."}]}The newest observation carries an extra key, latest, that the others do not. It is the string "true", not a boolean. Source (Results.series[0].data[0], 2026-09-08).
{"year":"2026","period":"M08","periodName":"August","latest":"true","value":"4.1","footnotes":[{}]}The household survey code table uses digits plus C, and defines 9 as the appropriations lapse and 12 as the population-control revision. Source (whole file, 2026-09-08).
footnote_code footnote_text 1 Data affected by changes in population controls. 10 Data for Q4 2025 were not produced. Data for October 2025 were not collected due to the federal government shutdown. 11 Annual estimates for 2025 are 11-month averages that exclude October. Data for October 2025 were not collected due to the federal government shutdown. 12 January 2026 estimates were revised to incorporate updated population controls. For more information, see www.bls.gov/cps/documentation.htm#pop. 2 Constructed on the 2002 Census Industry Classification from data originally coded on earlier classifications. Official series was not revised. 3 2000 forward coded on the 2002 Census Occupation Classification. 1983-99 constructed from data originally coded on earlier classifications. 4 2000 forward coded on the 2002 Census Industry Classification. 1983-99 constructed from data originally coded on earlier classifications. 7 Data do not meet publication criteria. 8 This series id code has been discontinued; data are available using the database tool at www.bls.gov/webapps/legacy/cpsatab8.htm. 9 Data unavailable due to the 2025 lapse in appropriations. C Corrected
The payroll survey table shares no code with it. Its codes are letters, its shutdown code is A, and P marks a preliminary value that will be revised. Source (whole file, 2026-09-08).
footnote_code footnote_text A Data unavailable due to the 2025 lapse in appropriations B 2025 annual average omits October data; CPI could not be collected due to the federal shutdown. D 2025 annual average omits one observation; data could not be collected due to the federal shutdown. E Impacted by 2025 lapse in appropriations. F Initial release of October 2025 data. I Seasonally Adjusted Independently. See www.bls.gov/opub/hom/ces/calculation.htm for details. P preliminary
The file sorts codes as text, so 10, 11 and 12 sit before 2, and C sits after 9. Reading it as an ordered list of severity or vintage is wrong. Source (first column, in file order, 2026-09-08).
footnote_code 1 10 11 12 2 3 4 7 8 9 C
The command
curl -sS 'https://api.bls.gov/publicAPI/v2/timeseries/data/LNS14000000'
{"status":"REQUEST_SUCCEEDED","responseTime":116,"message":[],"Results":{
"series":
[{"seriesID":"LNS14000000","data":[{"year":"2026","period":"M08","periodName":"August","latest":"true","value":"4.1","footnotes":[{}]},{"year":"2026","period":"M07","periodName":"July","value":"4.1","footnotes":[{}]}Checked 2026-09-08.
curl -sS -A 'x@y.com' 'https://download.bls.gov/pub/time.series/ln/ln.footnote'
footnote_code footnote_text 1 Data affected by changes in population controls. 10 Data for Q4 2025 were not produced. Data for October 2025 were not collected due to the federal government shutdown. 11 Annual estimates for 2025 are 11-month averages that exclude October. Data for October 2025 were not collected due to the federal government shutdown. 12 January 2026 estimates were revised to incorporate updated population controls. For more information, see www.bls.gov/cps/documentation.htm#pop. 2 Constructed on the 2002 Census Industry Classification from data originally coded on earlier classifications. Official series was not revised. 3 2000 forward coded on the 2002 Census Occupation Classification. 1983-99 constructed from data originally coded on earlier classifications. 4 2000 forward coded on the 2002 Census Industry Classification. 1983-99 constructed from data originally coded on earlier classifications. 7 Data do not meet publication criteria. 8 This series id code has been discontinued; data are available using the database tool at www.bls.gov/webapps/legacy/cpsatab8.htm. 9 Data unavailable due to the 2025 lapse in appropriations. C Corrected
Checked 2026-09-08.
curl -sS -A 'x@y.com' 'https://download.bls.gov/pub/time.series/ce/ce.footnote'
footnote_code footnote_text A Data unavailable due to the 2025 lapse in appropriations B 2025 annual average omits October data; CPI could not be collected due to the federal shutdown. D 2025 annual average omits one observation; data could not be collected due to the federal shutdown. E Impacted by 2025 lapse in appropriations. F Initial release of October 2025 data. I Seasonally Adjusted Independently. See www.bls.gov/opub/hom/ces/calculation.htm for details. P preliminary
Checked 2026-09-08.
curl -sS -A 'x@y.com' 'https://download.bls.gov/pub/time.series/ln/ln.footnote' | cut -f1 | tr '\n' ' '
footnote_code 1 10 11 12 2 3 4 7 8 9 C
Checked 2026-09-08.
| survey | footnote file | codes defined | no-data code | revision-related codes |
|---|---|---|---|---|
| Current Population Survey (LN series) | https://download.bls.gov/pub/time.series/ln/ln.footnote | 1, 2, 3, 4, 7, 8, 9, 10, 11, 12, C | 9 | 1, 12 (population controls), C (corrected) |
| Current Employment Statistics (CE series) | https://download.bls.gov/pub/time.series/ce/ce.footnote | A, B, D, E, F, I, P | A | P (preliminary), F (initial release of October 2025) |
Limits
- Two surveys were read. The CPI, JOLTS and producer price footnote files were not, so the claim is that codes are per-survey - proven by these two disagreeing - not that every survey has its own distinct alphabet.
- The dash was observed for one month in one series, October 2025. Whether BLS ever uses a different placeholder for a suppressed value, as opposed to an uncollected one, was not tested; code 7, data do not meet publication criteria, exists in the file but no row carrying it was found.
- download.bls.gov refuses any request whose User-Agent has no email address in it - the -A flag in these commands is load-bearing, not decoration.
- This page does not get you an earlier vintage. Nothing keyless was found that returns a BLS value as it stood on a past date; the footnote is the only marker that today's value differs from the one first published.
Open question
The CE file's code B reads "2025 annual average omits October data; CPI could not be collected" - CPI is a different survey from CE. Is that text misplaced, or does CE genuinely footnote a CPI-driven adjustment?