Skip to main content
POST
/
search
Execute a query
curl --request POST \
  --url https://api.eu.bronto.io/search \
  --header 'Content-Type: application/json' \
  --header 'X-BRONTO-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "select": [
    "min(response_time_ms)",
    "avg(response_time_ms)",
    "max(response_time_ms)"
  ],
  "from": [
    "[550e8400-e29b-41d4-a716-446655440000, 297bb888-83b1-44e0-8ab6-47879f1275a2]"
  ],
  "from_tags": [
    "environment:production"
  ],
  "from_expr": "log_id = '797655e0-bddd-4abe-97a4-e9e419a72baa' OR environment != 'production'",
  "time_range": "Last 10 minutes",
  "from_ts": 1709251200000,
  "to_ts": 1711390455601,
  "where": "ip='10.0.0.1'",
  "groups": [
    "[user, ip]"
  ],
  "limit": 50,
  "num_of_slices": 50,
  "from_sequence": 111721913,
  "most_recent_first": true,
  "explain_only": true,
  "async_enabled": false,
  "order_by": "<string>",
  "pagination_token": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "per_page": 3333
}
EOF
{
  "explain": {
    "Execution time (millis)": "353"
  },
  "result": [
    {
      "@time": "2024-03-27 10:25:40.632 UTC",
      "@sequence": "111721913",
      "@raw": "10.0.0.1 - - [27/Mar/2024:10:54:39 +0000] \"GET / HTTP/1.1\" 200 721 \"-\" \"ELB-HealthChecker/2.0\"",
      "@context": "https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both",
      "metadata": {
        "logId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "timestamp": 1711535140632,
        "sequence": 111721913,
        "origin": "10.0.0.1",
        "context": "https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both",
        "selectedKeys": {
          "@time": "2024-03-27 10:25:40.632 UTC"
        },
        "unselectedKeys": {
          "id": "message_0",
          "current_time": 1711535140
        }
      },
      "links": [
        {
          "rel": "context",
          "href": "https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both"
        }
      ]
    }
  ],
  "events": [
    {
      "@raw": "10.0.108.203 - - [27/May/2024:23:47:27 +0000] \"GET / HTTP/1.1\" 200 675 \"-\" \"ELB-HealthChecker/2.0\"",
      "@time": "2024-05-27 23:26:34.331 UTC",
      "@status": "info",
      "message_kvs": {
        "method": "GET",
        "statusCode": "200",
        "path": "/"
      },
      "attributes": {
        "$private_ip": "10.0.22.230",
        "$environment": "production"
      },
      "metadata": {
        "service_id": "23746675-7022-4985-bd74-4af9eba58d72",
        "timestamp": 1716853347801,
        "sequence": 111721913,
        "context": "\"https://api.eu.bronto.io/context?sequence=213&from=37bdf479-7c95-4e81-982a-25d0680fb602&timestamp=1716853354331&direction=both\"\n"
      },
      "links": [
        {
          "rel": "context",
          "href": "https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both"
        }
      ]
    }
  ],
  "groups": [
    {
      "group": "[US]",
      "count": 124,
      "stat": "average(bytes)",
      "value": 50325.25,
      "timeseries": [
        {
          "@timestamp": "1711535140632",
          "count": 40,
          "value": 35.625,
          "quantiles": {
            "min": 691,
            "p25": 713.75,
            "p50": 796,
            "p75": 847.5,
            "p90": 1237,
            "p95": 1331,
            "p99": 1331,
            "p999": 1331,
            "max": 1331
          }
        }
      ]
    }
  ],
  "groups_series": [
    {
      "name": "host123",
      "count": 124,
      "stat": "average(duration_millis)",
      "value": 50325.25,
      "quantiles": {
        "min": 691,
        "p25": 713.75,
        "p50": 796,
        "p75": 847.5,
        "p90": 1237,
        "p95": 1331,
        "p99": 1331,
        "p999": 1331,
        "max": 1331
      },
      "series_resolution_ms": 60000,
      "timeseries": [
        {
          "@timestamp": "1711535140632",
          "count": 40,
          "value": 35.625,
          "quantiles": {
            "min": 691,
            "p25": 713.75,
            "p50": 796,
            "p75": 847.5,
            "p90": 1237,
            "p95": 1331,
            "p99": 1331,
            "p999": 1331,
            "max": 1331
          }
        }
      ],
      "groups_series": [
        {
          "name": "host123",
          "count": 124,
          "stat": "average(duration_millis)",
          "value": 50325.25,
          "series_resolution_ms": 60000,
          "timeseries": [
            {
              "@timestamp": "1711535140632",
              "count": 40,
              "value": 35.625,
              "quantiles": {
                "min": 691,
                "p25": 713.75,
                "p50": 796,
                "p75": 847.5,
                "p90": 1237,
                "p95": 1331,
                "p99": 1331,
                "p999": 1331,
                "max": 1331
              }
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "select": [
      "host",
      "status",
      "method"
    ],
    "correlation_id": "00000000-0000-0000-0000-000000000000"
  },
  "totals": {},
  "pagination": {
    "next_page_url": "<string>"
  },
  "links": [
    {
      "rel": "next",
      "href": "<string>"
    }
  ]
}

Authorizations

​
X-BRONTO-API-KEY
string
header
required

Body

application/json
​
select
string[]
required

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)"
]
​
from
string[]

The ids of the logs to search. One of either the from or the from_expr parameters must be specified.

​
from_tags
string[]
deprecated

The tags filters for selecting the datasets. Each from_tags should be in the form <key>:<value>, e.g. environment:production. When multiple from_tags are provided, filters on the same tag key are evaluated with OR logic, while filters on tags with different keys are evaluated with AND logic (facet style search). e.g. [environment:production, team:A, team:B] will include all production datasets where the team tag is either B or A. One of either the logs or the from_tags parameters must be specified. If both are specified then from_tags takes precedence, and the logs value is ignored.

​
from_expr
string

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.

Example:

"log_id = '797655e0-bddd-4abe-97a4-e9e419a72baa' OR environment != 'production'"

​
time_range
string

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
integer

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
integer

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
string

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
string[]

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.

​
limit
integer
default:100

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.

Required range: 1 <= x <= 6666
Example:

50

​
num_of_slices
integer
default:10

The number of buckets to break the time series results into.

Example:

50

​
from_sequence
integer

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
boolean

Flag to indicate the order in which results should be returned.

Example:

true

​
explain_only
boolean
default:false

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

​
async_enabled
boolean
default:false

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.

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.

​
order_by
string

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 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.

​
pagination_token
string<uuid>

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.
​
per_page
integer

The number of records to return in the next page of results.

Usage Rules:

  • Used 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 range: 1 <= x <= 6666

Response

Search results

​
explain
object
​
result
object[]
​
events
object[]
​
groups
object[]
​
groups_series
object[]
​
metadata
object
​
totals
object
​
pagination
object
​
links
(Next Link · object | Previous Link · object | First Link · object | Status Link · object)[]

Navigation links for traversing the result set.