> ## 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 post /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: 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.brontobytes.io/core-features/log-search/query-syntax/. - 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. paths: /search: post: 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.brontobytes.io/core-features/log-search/query-syntax/. 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: postSearch requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSearchRequest' required: true 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: schemas: CreateSearchRequest: required: - select type: object properties: from: type: array description: > The ids of the logs to search. One of either the `from` or the `from_tags` parameters _must_ be specified. items: minItems: 1 uniqueItems: true type: string example: >- [550e8400-e29b-41d4-a716-446655440000, 297bb888-83b1-44e0-8ab6-47879f1275a2] from_tags: type: array description: > The tags to search. Each tag should be in the form `:`, e.g., `environment:production`. One of either the `from` or the `from_tags` parameters _must_ be specified. If _both_ are specified then `from_tags` takes precedence, and the `from` value is ignored. If the key or the value contain a `:` or `=` character, then these can be escaped by wrapping the entire key or value in double-quotes `"`. items: minItems: 1 uniqueItems: true type: string example: environment:production time_range: type: string 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. example: Last 10 minutes 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`. 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`. example: 1711390455601 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' select: type: array description: > The select parameter enables the selection of one or many rows or columns from your datasets. It can be used to select keys by name, e.g. `"select": ["ip_address", "status_code"]`, in which case the response will contain a list of log events with two columns containing ip addresses and status codes. Or it can be used with an aggregate function (count, max, min, avg, sum), e.g., `"select": ["avg(response_time_ms)", "max(response_time_ms)"]`, in which case the response will contain columns for the average response time, and max response time. Each row corresponds to a time slice, for example if you set `"num_of_slices": 10` and `"time_range": "Last 10 hours"`, then each row will contain the function result for each hour of data. The `@raw` internal attribute is always available for selection, and its values are the entire unparsed log events. example: - min(response_time_ms) - avg(response_time_ms) - max(response_time_ms) items: minItems: 1 type: string 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: minItems: 1 type: string example: '[user, ip]' limit: maximum: 6666 minimum: 1 type: integer 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. example: 50 default: 100 num_of_slices: type: integer description: The number of buckets to break the time series results into. example: 50 default: 10 from_sequence: type: integer 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. example: 111721913 most_recent_first: type: boolean description: Flag to indicate the order in which results should be returned. example: true explain_only: type: boolean 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. example: true default: false async_enabled: type: boolean 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. default: false QueryExplain: type: object properties: Execution time (millis): type: string description: Measure of time taken to execute the query. example: '353' 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 Bytes. 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 statusCode: '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/GroupTimeSeries' GroupSeriesItem: 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 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 format: int64 example: 60000 timeseries: type: array items: $ref: '#/components/schemas/GroupTimeSeries' groups_series: type: array description: The subgroups of the group (multi group-by) 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/GroupTimeSeries' 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 items: anyOf: - type: object properties: rel: type: string description: next example: next href: type: string description: >- For paginated event search queries, the URL which can be used to fetch the next page of results. format: uri - type: object properties: rel: type: string description: status example: 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 - message type: object properties: code: minimum: 200 type: integer description: The http response code. format: int32 correlation_id: type: string description: The unique identifier for the request. message: type: string GroupTimeSeries: type: object properties: '@timestamp': type: string description: Unix timestamp in milliseconds 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 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 ````