> ## Documentation Index > Fetch the complete documentation index at: https://docs.bronto.io/llms.txt > Use this file to discover all available pages before exploring further. # Run an ad-hoc timeseries query > Execute a one-off timeseries query or formula directly. This is not saved. Use for interactive mode or metrics explorer. ## OpenAPI ````yaml https://s3.eu-west-1.amazonaws.com/docs.brontobytes.io/redocusaurus/brontobytes.yaml post /timeseries/search openapi: 3.0.2 info: title: Bronto API license: name: Commercial version: 1.0.0 servers: - url: https://api.eu.bronto.io - url: https://api.us.bronto.io security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: api-keys description: > An Application Programming Interface (API) key is a unique identifier. The API Key must be provided as X-BRONTO-API-KEY in headers for the request to be authenticated and authorized by the API server according to the API Key's role. For further information about roles visit [our API Key docs] https://docs.bronto.io/manage/manage-api-keys - name: context description: > Context is a REST API resource that allows the retrieval of a specified number of log events (default of 100) around a log event of interest, e.g. when a number of log events were returned by a previous query and you then decide you want to see the 50 log events before one of those returned log events. Log events can be retrieved either before, after, or both before and after the specified log event. - name: exports description: > The Bronto Export API allows you to efficiently download large volumes of log data for further analysis. The data to be exported can be filtered by entering the search parameters \"from\", \"where\" and \"time_range\" as per a normal query in the \"search_details\" object. To export data the following steps are required: 1. Create an export using a POST request, which will return an \"export_id\", \"status\" and \"progress\". 2. Use the export id to get the status of the export task by sending a GET request, which will return \"status\" and \"progress\" with a value of percentage completed. When the export is completed, the \"status\" will be \"COMPLETE\" 3. Once the export task has completed you can download your data using curl (or similar) from the \"location\" URL returned in the GET response. - name: collections description: > Collections group datasets together. Each collection contains one or more datasets. - name: datasets description: > Datasets are a sequence of timestamped log events. Datasets can be searched to view events matching a filter or to perform statistical functions on matching events. - name: logs description: > Logs are a sequence of timestamped log events. Logs can be searched to view events matching a filter or to perform statistical functions on matching events. - name: search description: > The REST API for searching data uses queries based on a subset of SQL, with the syntax as per https://docs.bronto.io/query-syntax/overview - name: top-keys description: > Top-Keys is a REST API resource that allows you to easily retrieve the top keys for a specific log. - name: usage description: > Usage is a REST API resource that allows you to easily track your Bronto usage by retrieving usage data relating to data ingestion and amount of data searched, and allowing you to drill down for a specific dataset over a defined timeframe. - name: users description: > Users are given specific roles, where each role determines the user's permissions within the application. Those roles are as follows: - "Admin" role has permission for all actions on all entities in the application. - "Standard" role allows Read/Write and Delete actions on entities in non-sensitive areas of the application. - "ReadOnly" role allows only read actions and only on entities in non-sensitive areas of the application. - name: config_assistant description: > The Config Assistant APIs provide endpoints for creating or modifying observability agent configurations. - name: patterns description: > Patterns return the Pattern IDs, templates, and source log ID for all logs matching the given search criteria. paths: /timeseries/search: post: tags: - timeseries summary: Run an ad-hoc timeseries query description: > Execute a one-off timeseries query or formula directly. This is not saved. Use for interactive mode or metrics explorer. operationId: searchTimeseries requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchTimeseries' required: true responses: '200': description: Timeseries search results headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/MetricTimeseries' description: Map of the query/formula name and the related timeseries '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Request - Fair usage limits exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error - An error occurred on the server side. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SearchTimeseries: required: - queries - time_range type: object properties: limit: maximum: 10000 minimum: 1 type: integer description: | In a query with a group by, it limits the number of groups returned. It does not affect a query using aggregate functions. example: 50 default: 100 num_of_slices: maximum: 1440 minimum: 1 type: object description: The number of buckets to break the time series results into. example: 100 default: 100 delta: required: - enabled type: object properties: enabled: type: boolean description: Whether delta calculation is enabled. default: false natural: type: string description: > The reference time period used for delta comparison. Either `natural` or both `from_ts` and `to_ts` may be provided when `delta` is enabled. `natural` takes precedence over `from_ts`/`to_ts` if both are supplied. If no delta period is specified, the delta is computed against the previous equivalent time range. example: Previous month from_ts: type: integer description: | Start of the comparison time range (Unix epoch in milliseconds). format: int64 example: 1709251200000 to_ts: type: integer description: | End of the comparison time range (Unix epoch in milliseconds). format: int64 example: 1711390455601 time_range: type: object properties: from_ts: type: integer description: > The starting time (unix time in milliseconds) for which to query data. Must be used together with `to_ts`. This parameter is incompatible with `time_range`. format: int64 example: 1709251200000 to_ts: type: integer description: > The ending time (unix time in milliseconds) for which to query data. Must be used together with `from_ts`. This parameter is incompatible with `time_range`. format: int64 example: 1711390455601 natural: type: string description: > The natural time range for which to query data. Time range supported is from milliseconds to years. For an exact range, use `from_ts` and `to_ts` instead. example: Last 10 minutes formulas: maxItems: 5 minItems: 0 type: array description: a list of formulas that combine the queries results items: $ref: '#/components/schemas/MetricFormula' queries: maxItems: 6 minItems: 1 type: array description: the list of simple queries computed to generate the timeseries items: $ref: '#/components/schemas/MetricQuery' MetricTimeseries: required: - name - queries type: object properties: formulas: maxItems: 5 minItems: 0 type: array description: the list of formulas computed in the request items: $ref: '#/components/schemas/MetricFormula' queries: maxItems: 6 minItems: 1 type: array description: the list of simple queries computed in the request items: $ref: '#/components/schemas/MetricQuery' name: type: string description: the name of the query or formula this object refers to aggregates: type: array description: the aggregates computed for this formula/query example: - function: sum value: 18911006109 - function: count value: 58351920 items: type: object properties: function: type: string description: the name of the function value: type: number description: the computed value histogram: $ref: '#/components/schemas/Histogram' oneOf: - required: - function - value type: object - required: - function - histogram type: object is_exact: type: boolean description: true if the series result is exact, false if it is an approximation example: true series: type: array description: timeseries for non-group by queries items: $ref: '#/components/schemas/TimeSlice' groups_series: type: array description: timeseries for group by queries items: $ref: '#/components/schemas/GroupSeriesItem' delta: $ref: '#/components/schemas/MetricDelta' description: contains the timeseries for a query or a formula ErrorResponse: required: - code - correlation_id - details - type type: object properties: code: maximum: 599 minimum: 400 type: integer description: HTTP status code for the error response. format: int32 type: type: string description: >- HTTP reason phrase associated with the status code (e.g. "Not Found" for 404) example: Not Found correlation_id: type: string description: Unique identifier for the request, used for tracing and debugging. details: type: string description: Human-readable description of the error. example: Resource not found. description: Standard error response returned by the API when a request fails. example: bad_request_validation: summary: Bad Request - Validation Error description: Example error when request validation fails value: code: 400 type: Bad Request correlation_id: 95c6a974e3ab01209b6b0dfedb1b16c5 details: 'Validation failed: ''name'' field is required and cannot be empty' bad_request_invalid_type: summary: Bad Request - Invalid Metric Type description: Example error when an invalid metric type is provided value: code: 400 type: Bad Request correlation_id: 00d8a51bb2874f2583670317a4fb8db7 details: >- Invalid metric_type 'INVALID'. Must be one of: COUNTER, GAUGE, HISTOGRAM forbidden: summary: Forbidden Access description: Example error when user lacks required permissions value: code: 403 type: Forbidden correlation_id: 40276639de0f49d586e32edd8c4f6b34 details: >- Access denied. User does not have permission to create metric definition templates not_found: summary: Resource Not Found description: Example error when requested resource doesn't exist value: code: 404 type: Not Found correlation_id: 605f832bcfe44a1081441691c8d42253 details: >- Metric definition template with id '550e8400-e29b-41d4-a716-446655440000' not found rate_limit: summary: Rate Limit Exceeded description: Example error when API rate limit is exceeded value: code: 429 type: Too Many Requests correlation_id: 53909ed43c544531b7a555e295960437 details: >- Rate limit exceeded. Maximum 100 requests are allowed within a 5-minute window internal_server_error: summary: Internal Server Error description: Example error for unexpected server-side failures value: code: 500 type: Internal Server Error correlation_id: b129b8e0e66c41aa9541a30f67e38ce2 details: An unexpected error occurred while processing your request MetricFormula: required: - expression - name type: object properties: name: maxLength: 100 type: string description: >- The unique name, within a metric definition, of the formula. The name allows to identify the timeseries resulting from this formula in a search response example: error_rate expression: maxLength: 100 type: string description: > The expression that defines the formula. The formula elements refer, by name, to queries defined in the Metric Definition. When queries results have groups, the formula is computed over every group timeseries that appear in all group by queries. example: errors / total_requests * 100 aggregation: type: object properties: reduce_to: $ref: '#/components/schemas/ReduceTo' description: >- The reduction to apply to the timeseries to reduce it to a single value MetricQuery: type: object properties: name: maxLength: 255 type: string description: >- The unique name of the query within a Metric Definition or a Timeseries request. The name allows to identify the timeseries resulting from the query in the response or to compute formulas. Currently space cannot be in the name if the query has to be referenced in a formula select: type: array description: > The `select` parameter specifies the metric field to retrieve from the dataset. Only a single field can be selected, for example: `"select": ["cpu_usage"]`. The response returns a timeseries for the selected metric, with values aggregated across the requested time slices. example: - response_time_ms items: maxItems: 1 minItems: 1 type: string from: type: array description: >- List log IDs to query. One of either the `from` or `from_expr` parameters _must_ be specified. example: - 550e8400-e29b-41d4-a716-446655440000 - 297bb888-83b1-44e0-8ab6-47879f1275a2 items: type: string from_expr: maxLength: 255 type: string description: | An expression to identify the the logs or the metric to query. example: >- [log_type = 'java gc' and team = 'A', environment= 'production' AND region = 'eu-west-1', metric_name = 'system.cpu.utilization'] where: type: string description: > The where parameter is used to filter the results of your query. See https://docs.bronto.io/core-features/log-search/query-syntax for more details The filter can combine multiple terms using AND, OR, NOT. example: ip='10.0.0.1' groups: type: array description: > The groups parameter specifies a key to use to arrange the results returned by an aggregate function (such as count, max, min, avg, sum) into groups of values. The aggregate function returns a single value for each group. items: maxItems: 5 minItems: 0 type: string example: '[user, ip]' aggregation: maxItems: 1 minItems: 0 type: array description: the aggregation to apply to the selected metric field items: $ref: '#/components/schemas/Aggregation' unit_config: $ref: '#/components/schemas/QueryUnitConfig' oneOf: - required: - from - name - select - where type: object - required: - from_expr - name - select - where type: object Histogram: required: - buckets type: object properties: min: type: number description: The minimum value recorded, if available format: double example: 0 max: type: number description: The maximum value recorded, if available format: double example: 10 buckets: type: array description: List of the histogram buckets items: required: - high_bound - low_bound - name - value type: object properties: name: type: string description: The name of the bucket example: lower than 10 low_bound: type: number description: The lower bound of the bucket format: double example: 0 high_bound: type: number description: The upper bound of the bucket format: double example: 10 value: type: number description: The number of events within the bucket format: int64 description: Representation of an histogram TimeSlice: type: object properties: '@timestamp': type: string description: Unix timestamp in milliseconds of the start of this time slice example: '1711535140632' count: type: integer description: Count of the group key in the given time slice format: int64 example: 40 value: type: number description: >- The value of the statistical function for that group in the given time slice format: double example: 35.625 quantiles: type: object description: > Statistical distribution of the group’s values within the time slice, represented by key quantiles: - **min**: The minimum observed value. - **p25**: The 25th percentile (first quartile). - **p50**: The 50th percentile (median). - **p75**: The 75th percentile (third quartile). - **p90**: The 90th percentile. - **p95**: The 95th percentile. - **p99**: The 99th percentile. - **p999**: The 99.9th percentile, highlighting extreme outliers. - **max**: The maximum observed value. example: min: 691 p25: 713.75 p50: 796 p75: 847.5 p90: 1237 p95: 1331 p99: 1331 p999: 1331 max: 1331 histogram: $ref: '#/components/schemas/Histogram' oneOf: - required: - '@timestamp' - count - value type: object - required: - '@timestamp' - count - histogram type: object GroupSeriesItem: type: object properties: key: type: string description: The group by key of this series example: hostname name: type: string description: The group name associated with the timeseries example: host123 count: type: integer description: >- The number of times this group appeared in the logs/metrics across the timeseries format: int64 example: 124 stat: type: string description: The statistical function applied to the group example: average(duration_millis) value: type: number description: Overall value as result of the statistical function applied format: double example: 50325.25 histogram: $ref: '#/components/schemas/Histogram' quantiles: type: object description: > Statistical distribution of the group’s metric values shown through key quantiles: - **min**: The minimum observed value. - **p25**: The 25th percentile (first quartile). - **p50**: The 50th percentile (median). - **p75**: The 75th percentile (third quartile). - **p90**: The 90th percentile. - **p95**: The 95th percentile. - **p99**: The 99th percentile. - **p999**: The 99.9th percentile, highlighting extreme outliers. - **max**: The maximum observed value. example: min: 691 p25: 713.75 p50: 796 p75: 847.5 p90: 1237 p95: 1331 p99: 1331 p999: 1331 max: 1331 series_resolution_ms: type: number description: >- The resolution of the timeseries in milliseconds, so the length in milliseconds of a time slice format: int64 example: 60000 timeseries: type: array description: list of slices of this timeseries items: $ref: '#/components/schemas/TimeSlice' groups_series: type: array description: > The subgroups time series of the group. Provided only in case multiple group-by keys where specified in the query. Every object in this array is a group time series object with the same properties as the parent object (key, name, count, stat, timeseries etc). The groups series recursion repeats the number of group by keys specified in the query. items: type: object properties: name: type: string description: The group name example: host123 count: type: integer description: The number of times this group appeared in the logs format: int64 example: 124 stat: type: string description: The statistical function applied to the group example: average(duration_millis) value: type: number description: Overall value of the statistical function applied format: double example: 50325.25 series_resolution_ms: type: number description: The resolution of the timeseries in milliseconds format: int64 example: 60000 timeseries: type: array items: $ref: '#/components/schemas/TimeSlice' MetricDelta: type: object properties: start_time: type: integer description: The starting unix time in milliseconds of the previous period. end_time: type: integer description: The ending unix time in milliseconds of the previous period. aggregates: type: array description: Aggregated values for the comparison period. items: required: - function type: object properties: function: type: string description: the name of the function value: type: number description: the computed value over the delta period changes: type: array description: | Change between current and delta period aggregates. items: required: - function - value type: object properties: function: type: string description: the name of the function value: type: number description: Absolute difference. factor: type: number description: Relative delta. description: > Contains information about the change in the metric aggregations between the specified time range and the delta time range. If the delta time range is not specified, the delta is computed against the time range immediately preceding the requested one ReduceTo: type: string description: > Final reduction applied to the aggregated result. Commonly used when returning a single value instead of a full time series. default: avg enum: - avg - sum - min - max Aggregation: required: - time type: object properties: time: $ref: '#/components/schemas/TimeFunction' reduce_to: $ref: '#/components/schemas/ReduceTo' QueryUnitConfig: description: > Optional configuration describing the unit of the query's raw value and, where applicable, the unit it should be converted to for display. When omitted, the value is treated as a plain number. Currently used for UI display only. oneOf: - required: - input - type type: object properties: type: type: string enum: - data_size input: type: string description: The unit of the raw input value. enum: - bytes - kilobytes - megabytes - gigabytes - terabytes - petabytes - exabytes - zettabytes - yottabytes output: type: string description: > The unit to convert the value to for display. Use `auto` to automatically pick a unit based on the value's magnitude. Uses 1000 for the conversion factor. enum: - auto - bytes - kilobytes - megabytes - gigabytes - terabytes - petabytes - exabytes - zettabytes - yottabytes - required: - input - type type: object properties: type: type: string enum: - time input: type: string description: The unit of the raw input value. enum: - nanoseconds - microseconds - milliseconds - seconds - minutes - hours - days output: type: string description: > The unit to convert the value to for display. Use `auto` to automatically pick a unit based on the value's magnitude. enum: - auto - nanoseconds - microseconds - milliseconds - seconds - minutes - hours - days - required: - input - type type: object properties: type: type: string enum: - percentage input: type: string description: > The unit of the raw input value. `fraction` represents values between 0 and 1, `percent` represents values already scaled between 0 and 100. The output is always displayed as a percentage. enum: - fraction - percent TimeFunction: type: string description: Aggregation applied over time buckets. default: sum enum: - sum - avg - average - min - max - mean - count - median - p25 - p50 - p75 - p90 - p95 - p99 - p999 - histogram headers: RateLimitLimit: description: The request limit per time window. schema: type: integer example: 20 RateLimitRemaining: description: The number of requests left in the current time window. schema: type: integer example: 12 RateLimitReset: description: The number of seconds left in the current time window. schema: type: integer example: 13 securitySchemes: ApiKeyAuth: type: apiKey name: X-BRONTO-API-KEY in: header BearerAuth: type: http scheme: bearer bearerFormat: JWT ````