--- title: "Collect telemetry data" method: POST path: "/v1/telemetry/query" tags: ["Telemetry"] --- # Collect telemetry data `POST /v1/telemetry/query` Execute up to 1000 telemetry queries. A leaky bucket rate limiting mechanism is applied based on the calculated cost of each request. The cost is a linear combination of the number of requests, the number of queries per request, the estimated number of returned datapoints and the number of scanned shards. To minimize cost: - **Requests**: Send multiple queries in a single request (up to 1000). Make sure the total cost does not exceed your tier's bucket capacity. - **Queries per request**: Use a single query to select multiple fields instead of one query per field. - **Returned datapoints**: The estimate is based on the selected time range, the expected datapoint frequency and the provided `limit`. When no range is provided, a worst-case range is assumed. Always specify a time range and set `limit` as low as possible. - **Scanned shards**: Depends on the time range and expected datapoint frequency, but is unaffected by `limit`. A tight time range minimizes this component as well. If a request's cost would overflow the bucket, a `429` response is returned with a `Retry-After` header indicating how long to wait. If the cost exceeds the bucket's total capacity entirely, a `422` is returned. Ignoring `Retry-After` headers will result in a temporary 5-minute IP ban. Helper scripts for estimating request cost are available at [/assets/estimateCost.ts](/assets/estimateCost.ts) (TypeScript) and [/assets/estimateCost.py](/assets/estimateCost.py) (Python). ## Query parameters - `apiTier` string ## Request body - union - Def40[] — A list with up to 1000 telemetry queries. - `select` union[], required — An array specifying from which fields data must be collected. The array must have at least one item - union - string — A field for which data should be fetched - object - `field` string, required — A field for which data should be fetched - `function` 'sum' | 'min' | 'max' | 'mean', required — A function which is applied to aggregate the values of the specified field - `from` union, required - object - `measurement` string, required - `database` string, required - `retentionPolicy` string, required - object - `measurement` string, required - `namespace` union, required - object - `version` '1', required - `database` string, required - `retentionPolicy` string, required - object - `version` '2', required - `organization` string, required - `bucket` string, required - object - `version` 'IOx', required - `value` string, required - `where` object — A set of conditions which must be valid for the fetched data - `time` object[] — A list with either one or two time conditions which must be valid for the fetched data - `operator` '<' | '<=' | '>' | '>=' | '=' - `value` union — A timestamp, either a string in ISO8601 format, or a number representing a Unix time in milliseconds. - number - string, date-time - `tags` object — An object with string properties and values, specifying a tagset which must match the tagset of the returned data. At least one tag must be specified - `orderBy` 'ASC' | 'DESC' — The order in which datapoints should be returned - `limit` integer — The maxumum number of datapoints which should be returned. This should be an integer. - Def40 - `select` union[], required — An array specifying from which fields data must be collected. The array must have at least one item - union - string — A field for which data should be fetched - object - `field` string, required — A field for which data should be fetched - `function` 'sum' | 'min' | 'max' | 'mean', required — A function which is applied to aggregate the values of the specified field - `from` union, required - object - `measurement` string, required - `database` string, required - `retentionPolicy` string, required - object - `measurement` string, required - `namespace` union, required - object - `version` '1', required - `database` string, required - `retentionPolicy` string, required - object - `version` '2', required - `organization` string, required - `bucket` string, required - object - `version` 'IOx', required - `value` string, required - `where` object — A set of conditions which must be valid for the fetched data - `time` object[] — A list with either one or two time conditions which must be valid for the fetched data - `operator` '<' | '<=' | '>' | '>=' | '=' - `value` union — A timestamp, either a string in ISO8601 format, or a number representing a Unix time in milliseconds. - number - string, date-time - `tags` object — An object with string properties and values, specifying a tagset which must match the tagset of the returned data. At least one tag must be specified - `orderBy` 'ASC' | 'DESC' — The order in which datapoints should be returned - `limit` integer — The maxumum number of datapoints which should be returned. This should be an integer. ## Response `200` An array with for every query either an error message, the requested data or no data - union - Def41[] — An array of results, with the same number of items as the request body, where each item corresponds to the request body item with a matching index - union - object — If an error occured, the error property will be defined and contain an appropriate error message - `statement_id` integer, required — The index corresponding to matching request body item - `error` string, required — A string specifying an error. Typical errors are: 'Unauthorized', 'Invalid format: ....' or some more query-specific error message - object — If the query did return some data, the series property will be defined - `statement_id` integer, required — The index corresponding to matching request body item - `series` object[], required — The data matching the specified query - `name` string - `tags` object - `columns` string[] - `values` array[] - union[] - … - object — If there is no data matching the specified query, but the query is still valid, the series property is undefined - `statement_id` integer, required — The index corresponding to matching request body item - union - object — If an error occured, the error property will be defined and contain an appropriate error message - `statement_id` integer, required — The index corresponding to matching request body item - `error` string, required — A string specifying an error. Typical errors are: 'Unauthorized', 'Invalid format: ....' or some more query-specific error message - object — If the query did return some data, the series property will be defined - `statement_id` integer, required — The index corresponding to matching request body item - `series` object[], required — The data matching the specified query - `name` string - `tags` object - `columns` string[] - `values` array[] - union[] - union - … - object — If there is no data matching the specified query, but the query is still valid, the series property is undefined - `statement_id` integer, required — The index corresponding to matching request body item ## Other responses - `400` — Invalidly formatted body parameters - `401` — Authentication required or token invalid - `403` — You are trying to use an API tier that you are not allowed to use - `422` — Unprocessable Content. The request is syntactically valid, but its calculated operational cost exceeds the absolute maximum capacity of your subscription tier. This request will never succeed, even with an empty bucket. - `429` — Rate limit exceeded or IP temporarily banned. The client's leaky bucket does not have enough currently available capacity to cover the cost of the requested operation. --- [API](https://skmtc.dev/eniris/apis/eniris-metadata-telemetry-query-api.md) · [All operations](https://skmtc.dev/eniris/apis/eniris-metadata-telemetry-query-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/eniris/eniris-metadata-telemetry-query-api/revisions/fe3723575e19/schema)