Search endpoints

Execute a query

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

There are two types of search:

event search: allows you to specify a filter and view the matching events returned in the response. The response will be paginated if more than 50 matching events are returned.
statistical search: allows you to analyse events using a range of aggregate functions, such as count(), which return a number.

GET

curl --request GET \
  --url https://api.eu.bronto.io/search \
  --header 'X-BRONTO-API-KEY: <api-key>'

{
  "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

Query Parameters

from

string

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

from_tags

string

The tags to search. Each tag should be in the form <key>:<value>, 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 ".

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.

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 not to be used when using time_range.

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.

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.

select

string

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

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

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 statistical search using aggregate functions.

Required range: 1 <= x <= 6666

num_of_slices

integer

default:10

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

from_sequence

integer

The starting sequence for which to query data. This is more granular than a timestamp but also requires a from_ts param.

most_recent_first

boolean

Flag to indicate order in which results should be returned.

Response

200

application/json

Search results

explain

object

result

object[]

result.@time

string

Human readable timestamp of when this log event was ingested

Example:

"2024-03-27 10:25:40.632 UTC"

result.@sequence

string

The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp.

Example:

"111721913"

result.@raw

string

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\""

result.@context

string

A url that can be used to get the log events before and after this log event.

Example:

"https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both"

result.metadata

object

result.metadata.logId

string

The unique identifier of the log this log event came from

result.metadata.timestamp

integer

The timestamp of when this log event was ingested

Example:

1711535140632

result.metadata.sequence

integer

The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp.

Example:

111721913

result.metadata.origin

string

The identity of the sender if this log event.

Example:

"10.0.0.1"

result.metadata.context

string

A url that can be used to get the log events before and after this log event.

Example:

"https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72&timestamp=1711535140632&direction=both"

result.metadata.selectedKeys

object

The selected columns displayed in this result

Example:

{ "@time": "2024-03-27 10:25:40.632 UTC" }

result.metadata.unselectedKeys

object

The available columns not displayed in this result

Example:

{
  "id": "message_0",
  "current_time": 1711535140
}

result.links

object[]

events

object[]

events.@raw

string

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\""

events.@time

string

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"

events.@status

string

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"

events.message_kvs

object

Key-value pairs extracted from the log message

Example:

{
  "method": "GET",
  "statusCode": "200",
  "path": "/"
}

events.attributes

object

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"
}

events.metadata

object

The metadata of the event

events.links

object[]

groups

object[]

groups.group

string

The groupby key or keys used by this group

Example:

"[US]"

groups.count

integer

The number of times this group appeared in the logs

Example:

124

groups.stat

string

The statistical function applied to the group

Example:

"average(bytes)"

groups.value

number

Overall value of the statistical function applied

Example:

50325.25

groups.timeseries

object[]

groups.timeseries.@timestamp

string

Unix timestamp in milliseconds

Example:

"1711535140632"

groups.timeseries.count

integer

Count of the group key in the given time slice

Example:

40

groups.timeseries.value

number

The value of the statistical function for that group in the given time slice

Example:

35.625

groups.timeseries.quantiles

object

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
}

groups_series

object[]

groups_series.name

string

The group name

Example:

"host123"

groups_series.count

integer

The number of times this group appeared in the logs

Example:

124

groups_series.stat

string

The statistical function applied to the group

Example:

"average(duration_millis)"

groups_series.value

number

Overall value of the statistical function applied

Example:

50325.25

groups_series.quantiles

object

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
}

groups_series.series_resolution_ms

number

The resolution of the timeseries in milliseconds

Example:

60000

groups_series.timeseries

object[]

groups_series.timeseries.@timestamp

string

Unix timestamp in milliseconds

Example:

"1711535140632"

groups_series.timeseries.count

integer

Count of the group key in the given time slice

Example:

40

groups_series.timeseries.value

number

The value of the statistical function for that group in the given time slice

Example:

35.625

groups_series.timeseries.quantiles

object

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
}

groups_series.groups_series

object[]

The subgroups of the group (multi group-by)

groups_series.groups_series.name

string

The group name

Example:

"host123"

groups_series.groups_series.count

integer

The number of times this group appeared in the logs

Example:

124

groups_series.groups_series.stat

string

The statistical function applied to the group

Example:

"average(duration_millis)"

groups_series.groups_series.value

number

Overall value of the statistical function applied

Example:

50325.25

groups_series.groups_series.series_resolution_ms

number

The resolution of the timeseries in milliseconds

Example:

60000

groups_series.groups_series.timeseries

object[]

groups_series.groups_series.timeseries.@timestamp

string

Unix timestamp in milliseconds

Example:

"1711535140632"

groups_series.groups_series.timeseries.count

integer

Count of the group key in the given time slice

Example:

40

groups_series.groups_series.timeseries.value

number

The value of the statistical function for that group in the given time slice

Example:

35.625

groups_series.groups_series.timeseries.quantiles

object

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
}

metadata

object

metadata.select

string[]

The columns that were selected in the query request, and which appear in the results table.

Example:

["host", "status", "method"]

metadata.correlation_id

string

The identifier which uniquely identifies this query.

Example:

"00000000-0000-0000-0000-000000000000"

totals

object

pagination

object

links

object[]

Get the usage over a period of time for a user per log id.Retrieve forward configs

curl --request GET \
  --url https://api.eu.bronto.io/search \
  --header 'X-BRONTO-API-KEY: <api-key>'

{
  "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>"
    }
  ]
}

Api Keys endpoints

User endpoints

Context endpoints

Export endpoints

Logs endpoints

Usage endpoints

Search endpoints

Forward endpoints

Execute a query

Authorizations

Query Parameters

Response