> ## 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. # Execute a query > You can execute queries on your log data by using Bronto's syntax based on a subset of SQL as described in the documentation https://docs.bronto.io/query-syntax/overview. Bronto supports both the GET and POST methods for executing a query, however the POST method is preferred as it avoids problems related to maximum URL length when the query parameters are very long. In the context of the REST API, there are three distinct types queries which determine which parts of the response object are populated: + Event search queries return a list of events matching the specified filter. The response will be paginated if more than `limit` (default 50) matching events are returned. + Aggregate queries apply aggregate functions such as count(), sum(), max(), avg() to your log data, and return a number or a timeseries of numbers. + Group by aggregate queries return numerical results grouped according to the values for the attributes specified in the group by clause. The query type is determined by the combination of the `select` and `groups` parameters. ## OpenAPI ````yaml https://s3.eu-west-1.amazonaws.com/docs.brontobytes.io/redocusaurus/brontobytes.yaml get /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: /search: get: tags: - search summary: Execute a query description: > You can execute queries on your log data by using Bronto's syntax based on a subset of SQL as described in the documentation https://docs.bronto.io/query-syntax/overview. Bronto supports both the GET and POST methods for executing a query, however the POST method is preferred as it avoids problems related to maximum URL length when the query parameters are very long. In the context of the REST API, there are three distinct types queries which determine which parts of the response object are populated: + Event search queries return a list of events matching the specified filter. The response will be paginated if more than `limit` (default 50) matching events are returned. + Aggregate queries apply aggregate functions such as count(), sum(), max(), avg() to your log data, and return a number or a timeseries of numbers. + Group by aggregate queries return numerical results grouped according to the values for the attributes specified in the group by clause. The query type is determined by the combination of the `select` and `groups` parameters. operationId: search parameters: - name: from in: query description: > The ids of the logs to search. One of either the `from` or the `from_expr` parameters _must_ be specified. schema: minItems: 1 uniqueItems: true type: string example: - 550e8400-e29b-41d4-a716-446655440000 - 297bb888-83b1-44e0-8ab6-47879f1275a2 - name: from_expr in: query description: > Expression used to select a set of logs. The expression defines the criteria for which logs are included and is applied across all available logs to produce the input set. Supports logical operators (AND, OR), comparison operators (=, !=), and quoted string literals. schema: type: string example: >- log_id = '797655e0-bddd-4abe-97a4-e9e419a72baa' OR environment != 'production' - name: time_range in: query description: > The relative 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. schema: type: string examples: ms: value: Last 800 milliseconds sec: value: Last 10 seconds day: value: Last 2 days week: value: Last 3 weeks - name: from_ts in: query 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`. schema: type: integer example: 1709251200000 - name: to_ts in: query 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`. schema: type: integer example: 1711390455601 - name: where in: query 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. schema: type: string examples: kv: value: ip=10.0.0.1 count: value: count(*) sum: value: sum(payload_size) multiple_stat: value: count(*), sum(payload_size) internal: value: '@raw' multiple: value: payload_size, status, client_ip - name: select in: query description: >- The select parameter selects values of one or more specified keys and can be considered to be equivalent to returning columns from a table. It can select keys either by name, e.g. query params with select=ip_address or with an aggregate function (count, max, min, avg, sum) on the values of the specified key, e.g. query params with select=count(ip_address). Multiple selects can be used and they would separated by & in the query param, e.g. &select=count(ip_address)&select=count(hostname). The following internal columns are always available\: @time, @origin & @raw schema: type: string example: message - name: groups in: query 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. Multiple groups can be specified in the request if separated by &, e.g. query params with &groups=customer_id or &groups=customer_id&groups=hostname. schema: type: string example: - user - ip - name: limit in: query description: >- The maximum number of events that an event search should return. In a query with a group by, it limits the number of groups returned. It does not affect a query using aggregate functions. schema: maximum: 10000 minimum: 1 type: integer default: 100 example: 50 - name: num_of_slices in: query description: The number of buckets to break the time series results into. schema: type: integer default: 10 example: 50 - name: from_sequence in: query description: > Specifies the starting sequence number for the time range when used together with the `from_ts` parameter. Each log event has a sequence number which is unique within a millisecond, and can be used to query data with sub-millisecond time range precision. The sequence numbers are ordered such that earlier log events have lower sequence numbers. schema: type: integer example: 111721913 - name: most_recent_first in: query description: Flag to indicate the order in which results should be returned. schema: type: boolean example: true - name: explain_only in: query description: >- If set to `true` then only the `explain` element of the response will be populated. The `explain` element will contain the `Approximate bytes in time range` attribute which provides an estimate for the amount of data present in the time range for the selected datasets. This parameter is set to `false` by default. required: false schema: type: boolean example: true - name: async_enabled in: query description: > If set to `true` the server will respond in an asynchronous way: it will return immediately with a polling link (in the `links` element of the response body), which the client should check periodically to monitor the progress of the query and to receive partial results. This is useful for long running queries, and allows an API client to handle multiple requests concurrently without blocking. The behaviour of the async API is described [here](#tag/search/operation/getSearchStatus). If set to `false` the server will wait until the query has completed before returning a single `200` response with the completed results in the response body. required: false schema: type: boolean default: false - name: order_by in: query description: > Specifies the attribute by which to sort the result set, using SQL-style ORDER BY syntax. The expected format is ASC|DESC, for example: "duration_ms ASC". If the sort direction (ASC or DESC) is omitted, ascending order is used by default. Only one sort key may be specified. This parameter is only compatible with event search queries — i.e., queries that return a list of events and do not use aggregate functions (such as `count(*)`) in the `select` parameter. Sorting behavior is subject to certain restrictions — see the [Sort by Column](https://docs.bronto.io/Search-and-Visualize/Log-Search#sort-by-column) documentation for details. When the sort parameter is set, pagination links are not included in the response. The number of results returned is controlled solely by the limit parameter. required: false schema: type: string - name: pagination_token in: query description: > The token used to retrieve a specific page of results (next, prev, or first). **Usage Rules:** * This token is retrieved from the `href` in the `links` response object. * When this parameter is provided, all other search filters (e.g., query string, date range) are **ignored**, with the exception of `per_page`. required: false schema: pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ type: string format: uuid - name: per_page in: query description: > The number of records to return in the next page of results. **Usage Rules:** * Ued alongside `pagination_token` to modify the page size for the retrieved page. * If omitted, defaults to the page size defined in the initial query request. required: false schema: maximum: 10000 minimum: 1 type: integer responses: '200': description: 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 properties: explain: $ref: '#/components/schemas/QueryExplain' result: type: array items: $ref: '#/components/schemas/QueryResult' events: type: array items: $ref: '#/components/schemas/Event' groups: type: array items: $ref: '#/components/schemas/Group' groups_series: type: array items: $ref: '#/components/schemas/GroupSeriesItem' metadata: $ref: '#/components/schemas/QueryMetadata' totals: type: object pagination: $ref: '#/components/schemas/Pagination' links: $ref: '#/components/schemas/SearchCompletedLinksAsyncEnabled' '400': description: Bad Request - The body in the request is invalid. 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: 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 schemas: QueryExplain: type: object properties: Execution time (millis): type: string description: Measure of time taken to execute the query. example: '353' description: details on the query execution QueryResult: type: object properties: '@time': type: string description: Human readable timestamp of when this log event was ingested example: 2024-03-27 10:25:40.632 UTC '@sequence': type: string description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: '111721913' '@raw': type: string description: The full log line as received example: >- 10.0.0.1 - - [27/Mar/2024:10:54:39 +0000] "GET / HTTP/1.1" 200 721 "-" "ELB-HealthChecker/2.0" '@context': type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both metadata: type: object properties: logId: type: string description: The unique identifier of the log this log event came from format: uuid timestamp: type: integer description: The timestamp of when this log event was ingested example: 1711535140632 sequence: type: integer description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: 111721913 origin: type: string description: The identity of the sender if this log event. example: 10.0.0.1 context: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both selectedKeys: type: object description: The selected columns displayed in this result example: '@time': 2024-03-27 10:25:40.632 UTC unselectedKeys: type: object description: The available columns not displayed in this result example: id: message_0 current_time: 1711535140 links: type: array items: anyOf: - type: object properties: rel: type: string description: context example: context href: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both Event: type: object properties: '@raw': type: string description: The log message as received example: >- 10.0.108.203 - - [27/May/2024:23:47:27 +0000] "GET / HTTP/1.1" 200 675 "-" "ELB-HealthChecker/2.0" '@time': type: string description: > Human readable time of when this event was ingested into Bronto. The time is in UTC and in the format "YYYY-MM-DD HH:MM:SS.MMM UTC" example: 2024-05-27 23:26:34.331 UTC '@status': type: string description: > Indicates the severity of the event. Possible values are: - **info**: Denotes standard events or successful operations, such as HTTP 200 responses. - **warn**: Highlights potentially problematic situations that are not critical but may require attention, such as HTTP 4xx client errors. - **error**: Represents critical issues or failures, such as HTTP 5xx server errors or detected exceptions like stack traces. example: info message_kvs: type: object description: Key-value pairs extracted from the log message example: method: GET status_code: '200' path: / attributes: type: object description: > Additional details attached to the log event, such as resource attributes, environment settings, or custom attributes defined by the user. example: $private_ip: 10.0.22.230 $environment: production metadata: type: object properties: service_id: type: string description: The unique identifier of the service this event came from. format: uuid example: 23746675-7022-4985-bd74-4af9eba58d72 timestamp: type: integer description: Unix timestamp in milliseconds of when this event was ingested. example: 1716853347801 sequence: type: integer description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: 111721913 context: type: string description: >- A url that can be used to get the events before and after this event. format: uri example: > "https://api.eu.bronto.io/context?sequence=213&from=37bdf479-7c95-4e81-982a-25d0680fb602×tamp=1716853354331&direction=both" description: The metadata of the event links: type: array items: anyOf: - type: object properties: rel: type: string description: next example: context href: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both Group: type: object properties: group: type: string description: The groupby key or keys used by this group example: '[US]' 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(bytes) value: type: number description: Overall value of the statistical function applied format: double example: 50325.25 timeseries: type: array items: $ref: '#/components/schemas/TimeSlice' 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 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' QueryMetadata: type: object properties: select: type: array description: >- The columns that were selected in the query request, and which appear in the results table. example: - host - status - method items: type: string correlation_id: type: string description: | The identifier which uniquely identifies this query. example: 00000000-0000-0000-0000-000000000000 Pagination: type: object properties: next_page_url: type: string description: The url to fetch the next set of results format: uri SearchCompletedLinksAsyncEnabled: type: array description: Navigation links for traversing the result set. items: anyOf: - title: Next Link type: object properties: rel: type: string description: Indicates this link points to the next page of results. enum: - next href: type: string description: The URL to fetch the next page of results. format: uri - title: Previous Link type: object properties: rel: type: string description: Indicates this link points to the previous page of results. enum: - prev href: type: string description: > The URL to fetch the previous page of results. **Note:** This link is only present if you have navigated past the first page. format: uri - title: First Link type: object properties: rel: type: string description: Indicates this link points to the first page of results. enum: - first href: type: string description: The URL to fetch the first page of results. format: uri - title: Status Link type: object properties: rel: type: string description: Indicates this link points to the query status. enum: - status href: type: string description: > The URL to fetch the query's status. See more information about the async api [here](#tag/search/operation/getSearchStatus). format: uri 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 TimeSlice: required: - '@timestamp' - count - value 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 securitySchemes: ApiKeyAuth: type: apiKey name: X-BRONTO-API-KEY in: header BearerAuth: type: http scheme: bearer bearerFormat: JWT ````