Data versions

Available starting 2026-10-12

The dataVersion parameter and data version v2026-11-10 are available starting 2026-10-12.

As Clarity develops better techniques for processing and aggregating measurements, we may choose to reprocess your data. When we expect reprocessing to have a large impact, we may give you a way to control when you adopt the new values. That lets you try the new values and give us feedback for weeks before they become the default. You can choose to accelerate the adoption or delay it until the expected retirement.

A new version is rolled out in stages: preview, go live, deprecation and retirement. At any time there are only one or two versions available. One is the default, and there may be another in preview or deprecated.

When you request measurements, recent or historical, the dataVersion parameter chooses which version of the data you receive.

date	"legacy"	"v2026-11-10"
2023	default
2026-10-12	default	in preview
2026-11-10	deprecated	default
2027-01-11	retired	default

A data version does not change the shape of a response. The same metrics come back with the same attributes, and a CSV or Parquet file has the same columns, under every version. Only what value, qcAssessment and qcFlags carry can differ. raw and status are the same under every version.

v2026-11-10

This version introduces three new QC flags that apply only to 24-hour rolling means, NowCast aggregates, and their associated AQIs. No other metrics are affected.

QC.I.AGG.001 — too few hours reported

A 24-hour rolling mean where the device reported fewer than 18 of the 24 hours. The metric reports invalid, with QC.I.AGG.001 in qcFlags. value is unchanged. Under legacy, the same period reports valid, with no flags.

For example, a pm2_5ConcMass24HourRollingMean for a device that reported 12 of the last 24 hours:

field	legacy	v2026-11-10
qcAssessment	"valid"	"invalid"
qcFlags	[]	["QC.I.AGG.001"]

QC.I.AGG.002 — too few hours calibrated

A 24-hour rolling mean where the device reported at least 18 hours, but fewer than 18 of them have a calibrated value. The metric reports invalid, with QC.I.AGG.002 in qcFlags. value is unchanged. Under legacy, the same period reports valid, with no flags.

This flag concerns the calibrated value only. If you read raw, you may disregard it.

For example, a pm2_5ConcMass24HourRollingMean for a device that reported 22 of the last 24 hours, of which only 10 have a calibrated value:

field	legacy	v2026-11-10
qcAssessment	"valid"	"invalid"
qcFlags	[]	["QC.I.AGG.002"]

QC.W.FLT.001 — hours filtered out

Some hours in the period failed QC, but enough remain for a complete aggregate. The metric then reports:

• value: the aggregate over the hours that passed, leaving out the ones that failed
• qcAssessment: valid
• qcFlags: ["QC.W.FLT.001"], in place of the flags of the hours left out

The W in the flag means it is a warning. Warnings do not invalidate a value, so the metric stays valid.

Under legacy, the same period reports the aggregate over every hour, invalid, and the flags that occurred.

For example, a pm2_5ConcMass24HourRollingMean where 3 of the 24 hours failed an out-of-bounds check:

field	legacy	v2026-11-10
value	14.86	9.73
qcAssessment	"invalid"	"valid"
qcFlags	["QC.I.OOB.001"]	["QC.W.FLT.001"]

An aggregate is complete when it has enough hours that passed QC and calibration:

metric	complete when
24-hour rolling mean	at least 18 of the 24 hours
PM NowCast	at least 2 of the 3 most recent hours
Ozone NowCast	the EPA's completeness rules for the ozone NowCast

When too few hours remain, the metric matches the legacy response: value is calculated using all hours, qcFlags is the union of all the hours' flags, and qcAssessment is invalid.

How to request versions

Send dataVersion beside your usual parameters:

{
    "org": "myorg1234",
    "datasourceIds": ["DS123456"],
    "outputFrequency": "hour",
    "dataVersion": "v2026-11-10",
    "qcAssessment": true,
    "qcFlags": true
}

qcAssessment and qcFlags are optional. value is quality-controlled whether or not you request them, but without them you cannot see which periods are incomplete.

What you get depends on what you send:

you send	you get
no dataVersion	the default version. Your requests move to a new version on the date it becomes the default
an available version	that version, until it is retired
a retired version	the default version
a version that does not exist	an error

We will announce any change to the default on the Revisions page in advance.

A continuation token remembers the dataVersion of the request that created it. If that request omitted it, continuing the token follows the default, as the request would have.