--- title: "Query time series analytics" method: POST path: "/environments/{envId}/analytics/time-series" tags: ["computation"] --- # Query time series analytics `POST /environments/{envId}/analytics/time-series` Return data points over time with optional grouping by facets. Time series responses will include the lower and upper bound of the time range as the first and last buckets. ## Path parameters - `envId` string, required ## Request body - TimeSeriesRequest — A time series request is a request to obtain data points over time, organized by a specified interval. The time series buckets can be themselves nested by facets, allowing to group data by multiple nested facets over time. - `interval` union, required — A fixed time interval for time series analytics queries. Intervals are be expressed in milliseconds or duration strings (e.g., 10s, 1m, 5h). - string — Shorthand for expressing interval in seconds, minutes, hours or days as a string - number — Interval in milliseconds - `timeRange` TimeRange, required — Time range for analytics queries - `from` string, date-time, required — Start timestamp as an ISO 8601 date string or an epoch unix timestamp - `to` string, date-time, required — End timestamp as an ISO 8601 date string or an epoch unix timestamp - `by` FacetName[] — List of facet names to group time-series buckets (up to two facets) - `limit` integer — Maximum number of nested buckets to return - `filters` Filter[] — Top-level time series filters - union — Filter specification for analytics queries. Filters can be used at the top level of a request to refine the analytics results, or nested within a metrics to refine specific measures. - StringFilter — Filter specification for string values - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` string, required — Filter value (string for EQ) - NumberFilter — Filter specification for numeric values - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` integer, required — Filter value (number for LTE/GTE) - ArrayFilter — Filter specification for array values. - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` string[], required — Filter value (array for IN operator) - `metrics` FacetMetricRequest[], required — List of facet metric requests to process - `name` 'HTTP_REQUESTS' | 'HTTP_ERRORS' | 'HTTP_ERROR_RATE' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'LLM_PROMPT_TOKEN_SENT' | 'LLM_PROMPT_TOKEN_RECEIVED' | 'LLM_PROMPT_TOKEN_SENT_COST' | 'LLM_PROMPT_TOKEN_RECEIVED_COST' | 'LLM_PROMPT_TOTAL_TOKEN' | 'LLM_PROMPT_TOKEN_TOTAL_COST' | 'MESSAGE_PAYLOAD_SIZE' | 'MESSAGES' | 'MESSAGE_ERRORS' | 'MESSAGE_GATEWAY_LATENCY' | 'EDGE_DETECTION_COUNT' | 'EDGE_TOKENS_IN' | 'EDGE_TOKENS_OUT' | 'EDGE_HEARTBEAT_COUNT' | 'NATIVE_CONNECTIONS_SUMMARY' | 'NATIVE_MESSAGES_PRODUCED_DOWNSTREAM' | 'NATIVE_MESSAGES_PRODUCED_UPSTREAM' | 'NATIVE_MESSAGES_CONSUMED_DOWNSTREAM' | 'NATIVE_MESSAGES_CONSUMED_UPSTREAM' | 'NATIVE_BYTES_PRODUCED_DOWNSTREAM' | 'NATIVE_BYTES_PRODUCED_UPSTREAM' | 'NATIVE_BYTES_CONSUMED_DOWNSTREAM' | 'NATIVE_BYTES_CONSUMED_UPSTREAM' | 'NATIVE_ACTIVE_CONNECTIONS_DOWNSTREAM' | 'NATIVE_ACTIVE_CONNECTIONS_UPSTREAM' | 'NATIVE_AUTHENTICATIONS_SUCCESS_DOWNSTREAM' | 'NATIVE_AUTHENTICATIONS_SUCCESS_UPSTREAM' | 'NATIVE_AUTHENTICATIONS_FAILURE_DOWNSTREAM' | 'NATIVE_AUTHENTICATIONS_FAILURE_UPSTREAM' | 'NATIVE_OPERATIONS_RECEIVED' | 'NATIVE_OPERATIONS_FORWARDED' | 'NATIVE_OPERATIONS_ANSWERED' | 'NATIVE_OPERATIONS_COMPLETED' | 'NATIVE_OPERATION_GATEWAY_REQUEST_DURATION' | 'NATIVE_OPERATION_BROKER_DURATION' | 'NATIVE_OPERATION_GATEWAY_RESPONSE_DURATION', required — Available metric names for analytics queries - `measures` MeasureName[] — List of measures to compute for this metric - `filters` Filter[] — Request-level filters - union — Filter specification for analytics queries. Filters can be used at the top level of a request to refine the analytics results, or nested within a metrics to refine specific measures. - StringFilter — Filter specification for string values - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` string, required — Filter value (string for EQ) - NumberFilter — Filter specification for numeric values - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` integer, required — Filter value (number for LTE/GTE) - ArrayFilter — Filter specification for array values. - `name` 'API' | 'APPLICATION' | 'PLAN' | 'API_PRODUCT' | 'GATEWAY' | 'TENANT' | 'ZONE' | 'HTTP_METHOD' | 'HTTP_STATUS_CODE_GROUP' | 'HTTP_STATUS' | 'HTTP_PATH' | 'HTTP_PATH_MAPPING' | 'HOST' | 'GEO_IP_COUNTRY' | 'GEO_IP_REGION' | 'GEO_IP_CITY' | 'GEO_IP_CONTINENT' | 'CONSUMER_IP' | 'HTTP_USER_AGENT_OS_NAME' | 'HTTP_USER_AGENT_DEVICE' | 'MESSAGE_CONNECTOR_TYPE' | 'MESSAGE_CONNECTOR_ID' | 'MESSAGE_OPERATION_TYPE' | 'MESSAGE_SIZE' | 'MESSAGE_COUNT' | 'MESSAGE_ERROR_COUNT' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'LLM_PROXY_MODEL' | 'LLM_PROXY_PROVIDER' | 'MCP_PROXY_METHOD' | 'MCP_PROXY_TOOL' | 'MCP_PROXY_RESOURCE' | 'MCP_PROXY_PROMPT' | 'API_TYPE' | 'ERROR_KEY' | 'REQUEST_ID' | 'TRANSACTION_ID' | 'EDGE_PROVIDER' | 'EDGE_PROCESS' | 'EDGE_CLIENT' | 'EDGE_TYPE' | 'EDGE_VERSION' | 'EDGE_MODEL' | 'EDGE_TOOL' | 'NATIVE_CONNECTION_STATUS' | 'NATIVE_FAILURE_SIDE' | 'NATIVE_CLIENT_ID' | 'NATIVE_TOPIC' | 'NATIVE_OPERATION' | 'URI' | 'ENTRYPOINT', required — Available filter names for filtering analytics data - `operator` 'EQ' | 'IN' | 'LTE' | 'GTE' | 'CONTAINS', required — Filter operator - `value` string[], required — Filter value (array for IN operator) - `sorts` Sort[] — Array of sort criteria. Each sort criteria contains a name and order. - `measure` 'AVG' | 'MIN' | 'MAX' | 'P50' | 'P90' | 'P95' | 'P99' | 'COUNT' | 'PERCENTAGE' | 'SUM', required — Measure name identifier. Represents the type of measure/aggregation applied to a metric. - `order` 'ASC' | 'DESC', required — Sort order - `ranges` NumberRange[] — Ranges to apply to facet metrics. At the moment, only number ranges are supported. - `from` number, required - `to` number, required ## Response `200` Time series analytics response - TimeSeriesResponse — Response for time series query - contains time-ordered data points - `metrics` object[], required — List of time series metric responses. Root level buckets are TimeSeriesBucketList, nested buckets inside are regular BucketList. - `name` 'HTTP_REQUESTS' | 'HTTP_ERRORS' | 'HTTP_ERROR_RATE' | 'HTTP_REQUEST_CONTENT_LENGTH' | 'HTTP_RESPONSE_CONTENT_LENGTH' | 'HTTP_ENDPOINT_RESPONSE_TIME' | 'HTTP_GATEWAY_RESPONSE_TIME' | 'HTTP_GATEWAY_LATENCY' | 'LLM_PROMPT_TOKEN_SENT' | 'LLM_PROMPT_TOKEN_RECEIVED' | 'LLM_PROMPT_TOKEN_SENT_COST' | 'LLM_PROMPT_TOKEN_RECEIVED_COST' | 'LLM_PROMPT_TOTAL_TOKEN' | 'LLM_PROMPT_TOKEN_TOTAL_COST' | 'MESSAGE_PAYLOAD_SIZE' | 'MESSAGES' | 'MESSAGE_ERRORS' | 'MESSAGE_GATEWAY_LATENCY' | 'EDGE_DETECTION_COUNT' | 'EDGE_TOKENS_IN' | 'EDGE_TOKENS_OUT' | 'EDGE_HEARTBEAT_COUNT' | 'NATIVE_CONNECTIONS_SUMMARY' | 'NATIVE_MESSAGES_PRODUCED_DOWNSTREAM' | 'NATIVE_MESSAGES_PRODUCED_UPSTREAM' | 'NATIVE_MESSAGES_CONSUMED_DOWNSTREAM' | 'NATIVE_MESSAGES_CONSUMED_UPSTREAM' | 'NATIVE_BYTES_PRODUCED_DOWNSTREAM' | 'NATIVE_BYTES_PRODUCED_UPSTREAM' | 'NATIVE_BYTES_CONSUMED_DOWNSTREAM' | 'NATIVE_BYTES_CONSUMED_UPSTREAM' | 'NATIVE_ACTIVE_CONNECTIONS_DOWNSTREAM' | 'NATIVE_ACTIVE_CONNECTIONS_UPSTREAM' | 'NATIVE_AUTHENTICATIONS_SUCCESS_DOWNSTREAM' | 'NATIVE_AUTHENTICATIONS_SUCCESS_UPSTREAM' | 'NATIVE_AUTHENTICATIONS_FAILURE_DOWNSTREAM' | 'NATIVE_AUTHENTICATIONS_FAILURE_UPSTREAM' | 'NATIVE_OPERATIONS_RECEIVED' | 'NATIVE_OPERATIONS_FORWARDED' | 'NATIVE_OPERATIONS_ANSWERED' | 'NATIVE_OPERATIONS_COMPLETED' | 'NATIVE_OPERATION_GATEWAY_REQUEST_DURATION' | 'NATIVE_OPERATION_BROKER_DURATION' | 'NATIVE_OPERATION_GATEWAY_RESPONSE_DURATION', required — Available metric names for analytics queries - `unit` 'BYTES' | 'MILLISECONDS' | 'NUMBER' | 'PERCENT' — Unit of measurement for metrics. Specifies the unit in which the metric values are expressed. - `buckets` TimeSeriesBucket[] — List of time series buckets ordered chronologically. Nested buckets inside are regular BucketList, not TimeSeriesBucketList. - union — A time-series bucket represents a single time-series bucket. Buckets can be nested and eventually lead to a leaf bucket with measures. - TimeSeriesBucketLeaf — A leaf bucket represents a set of measure values for a given time series key. - `type` 'LEAF', required — Indicates this bucket is a time series leaf node containing measures. - `key` string, date-time, required — The time series bucket timestamp key (ISO 8601), leading to measures. - `timestamp` integer, required — Timestamp in milliseconds since Unix epoch (optional) - `measures` Measure[], required — Array of measure results. Each measure contains a name and value. The measures array is always represented as the leaf node of the buckets tree for other types of analytics requests. Example: [{"name": "COUNT", "value": 2984}, {"name": "AVG", "value": 89.5}] - `name` 'AVG' | 'MIN' | 'MAX' | 'P50' | 'P90' | 'P95' | 'P99' | 'COUNT' | 'PERCENTAGE' | 'SUM', required — Measure name identifier. Represents the type of measure/aggregation applied to a metric. - `value` number, required — The measure value. - TimeSeriesBucketGroup — A bucket group represents a bucket that nests facet buckets for a given time series key. - `type` 'GROUP', required — Indicates this bucket is a time-series group node containing buckets. - `key` string, date-time, required — The time series bucket timestamp key (ISO 8601) - `timestamp` integer, required — Timestamp in milliseconds since Unix epoch (optional) - `buckets` Bucket[], required — List of buckets that can contain either measures or nested buckets - union — A bucket represents a single facet bucket. Buckets can be nested and eventually lead to a leaf bucket with measures. - … ## Other responses - `400` — Bad request - Invalid Time Series Request - `500` — Internal server error while computing time series. --- [API](https://skmtc.net/gravitee-io/apis/gravitee-io-apim-management-api-analytics.md) · [All operations](https://skmtc.net/gravitee-io/apis/gravitee-io-apim-management-api-analytics/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gravitee-io/gravitee-io-apim-management-api-analytics/revisions/ff8d60356a08/schema)