Run Query

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 asynchronous!

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"
  }
}