Skip to content

Historical measurements - Poll report status

GET {baseURl}/v2/report-request/:reportId
Status and results for a requested report.

Example
https://clarity-data-api.clarity.io/v2/report-request/JB000001

Headers

  • x-api-key: the API key string.

Request

path parameter description
reportId string The report ID that was returned when the report was requested. See Request report.
Example "JB000001"

Response

attribute description
reportId string The reportId.
Example "JB000001"
reportStatus string One of in-progress, succeeded, or failed.
message string Details about the success or failure of the report.
report string The requested report.
query object Other parameters as passed to the original report request.
urls array List of urls for fetching report result file(s).
Contains only one element currently.
In the future, very long reports may span more than one file.
urlsExpireAt string The timestamp when the temporary urls in this response will expire.

Example 200 Response

{
    "reportId": "JBZZ6FQ8XX",
    "reportStatus": "succeeded",
    "report": "reference-site-measurements",
    "query": {
        "endTime": "2023-06-02T00:00:00.000Z",
        "outputFrequency": "hour",
        "refSiteIds": [
            "RCR7X5QP"
        ],
        "startTime": "2022-06-01T00:00:00.000Z"
    },
    "urls": [
        "https://a.very.long/temporary/url"
    ],
    "urlsExpireAt": "2023-08-01T01:01:27.718Z"
}

Example report contents

If you download one of the urls, you will get a gzip encoded CSV file or a Parquet file.

Here is an example two-line csv file after uncompressing. Among other things, it illustrates how:

  • column names or values may be enclosed in double quotes
  • qcFlags is further encoded as JSON inside a double-quoted string
"datasourceId","sourceId","sourceType","outputFrequency","time","locationLatitude","locationLongitude","pm2_5ConcMassIndividual.qcAssessment","pm2_5ConcMassIndividual.qcFlags","pm2_5ConcMassIndividual.raw","pm2_5ConcMassIndividual.status","pm2_5ConcMassIndividual.value"
"DLQVY2720","S4VXGKKG","CLARITY_NODE","minute","2024-10-06T00:39:09.918Z",19.68000000,-155.37000000,"valid","[]",3.00,"calibrated-ready",5.51
"DLQVY2720","S4VXGKKG","CLARITY_NODE","minute","2024-10-06T00:54:10.157Z",19.68000000,-155.37000000,"invalid","[""QC.I.OOB.001"",""QC.I.OOB.002""]",3010.00,"calibrated-ready",556.10