#docs #api #Advanced

Run Query

Using the TelemetryDeck API, you can run a query and retrieve its results

Authorization

You need a Bearer Token to authenticate against the TelemetryDeck API. Our article Getting an API Token explains how to get a Bearer Token.

TelemetryDeck Query Language

TelemetryDeck Query Language (TQL) is a JSON-based language for querying time-series data stored in TelemetryDeck. You can either write a query by hand, or generate a query from an insight.

It’s all async!

The query API is asynchronous. When you post a query to the API, it returns a task ID. You can then use the task ID to check the status of the query, and once it is succeeded, retrieve the last successful results.

Step 1: Run the query

To submit your query to the API, POST it to the /api/v3/query/calculate-async/ endpoint. As a return, you’ll receive a task ID. Hold on to that.

Request:

POST /api/v3/query/calculate-async/ HTTP/1.1
Authorization: Bearer 🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻
Content-Type: application/json
Host: api.telemetrydeck.com

{
"aggregations": [
{
"fieldName": "count",
"name": "count",
"type": "longSum"
}
],
"dataSource": "telemetry-signals",
"dimension": {
"dimension": "modelName",
"outputName": "modelName",
"type": "default"
},
"filter": {
"fields": [
{
"dimension": "appID",
"type": "selector",
"value": "B97579B6-FFB8-4AC5-AAA7-DA5796CC5DCE"
},
{
"dimension": "isTestMode",
"type": "selector",
"value": "false"
}
],
"type": "and"
},
"granularity": "all",
"metric": {
"metric": "count",
"type": "numeric"
},
"queryType": "topN",
"relativeIntervals": [
{
"beginningDate": {
"component": "day",
"offset": -30,
"position": "beginning"
},
"endDate": {
"component": "day",
"offset": 0,
"position": "end"
}
}
],
"threshold": 200
}

Result:

{
"queryTaskID": "55b3487da8018369"
}

Psst! There is a synchronous API for this too, but it’s not recommended. To try it, leave out the “-async” part of the URL. Note that longer-running queries will be terminated by this API, and we’re not yet sure if we’re going to support this API at all in the future.

Step 2: Check the status of the query

This API endpoint will tell you if your query is finished or still running. It will return a JSON object with a “status” field, which will be one of these values:

  • running - The query is still executing. Check again in a second or so.
  • successful - The query has finished successfully. You can now retrieve the results.
  • failed - The query has failed. There will be a second key, error which will contain a description of the error.
GET /api/v3/task//status/ HTTP/1.1
Authorization: Bearer 🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻
Host: api.telemetrydeck.com

Response:

{
"status": "successful"
}

Step 3: Retrieve the results

Once your query task status is successful, you can retrieve the results.

GET /api/v3/task/55b3487da8018369/value/ HTTP/1.1
Authorization: Bearer 🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻🐻
Host: api.telemetrydeck.com

Response:

{
"calculationDuration": 0.21845901012420654,
"calculationFinishedAt": "2022-07-11T14:00:44+0000",
"result": {
"rows": [
{
"result": [
{
"count": 516,
"modelName": "iPhone13,1"
},

// ...

{
"count": 2,
"modelName": "iPad8,6"
}
],
"timestamp": "2022-06-11T00:00:00+0000"
}
],
"type": "topNResult"
}
}