Skip to main content
GET
/
usage
Retrieve usage metrics over time
curl --request GET \
  --url https://api.eu.bronto.io/usage \
  --header 'X-BRONTO-API-KEY: <api-key>'
{
  "id": "f0e1d2c3-b4a5-6789-0abc-def123456789#ingestion-org_usage",
  "name": "ingestion_org_usage",
  "filter": "event_type='log_usage' AND collection_name!='.usage' AND collection_name!='.audit-trail'",
  "stat": "SUM",
  "key": "bytes_total",
  "group_keys": [],
  "logs": [
    ""
  ],
  "from_tags": [],
  "aux": {},
  "total_count": 3790,
  "total_value": 12961699,
  "is_exact": true,
  "series": [
    {
      "@time": "Sun Mar 01 00:00:00 UTC 2026",
      "@timestamp": "1772323200000",
      "count": "546",
      "value": "1274155.0",
      "quantiles": {}
    },
    {
      "@time": "Mon Mar 02 03:14:15 UTC 2026",
      "@timestamp": "1772421255737",
      "count": "679",
      "value": "2688361.0",
      "quantiles": {}
    }
  ],
  "groups_series": [],
  "delta": {
    "start_time": 0,
    "end_time": 0,
    "total_count": 0,
    "total_value": 0,
    "delta_value": 0,
    "delta_factor": 0
  }
}

Authorizations

​
X-BRONTO-API-KEY
string
header
required

Query Parameters

​
time_range
string

The period to calculate the usage for.

​
timeRange
string

The period to calculate the usage for.

​
num_of_slices
integer

The num_of_slices parameter defines how the time range is divided into intervals. It is optional, and if not provided, a default value is applied. The default number of slices is 1 minute granularity for up to 12 hours time range and 20 minutes granularity for longer than 12 hours time range up to 720 slices. - default for 20 minutes time window: 20 slices - default for 12 hour time window: 720 slices - default for 1 day time window: 72 slices (1 slice per 20 minutes) - default for 10 days time window: 720 slices (1 slice per 20 minutes) - default for 30 days time window: 720 slices (max number of slices allowed)

​
usage_type
enum<string>

The type of usage to query.

Available options:
ingestion,
search,
export
​
delta
boolean

Enables calculation of the difference between the current and previous time range values. When set to true, the response includes a delta object with the computed difference and its relative change. Defaults to false.

​
delta_time_range
string

The time period for which to query data for delta comparison. Either delta_time_range or both delta_from_ts and delta_to_ts can be provided if delta is enabled. If delta_time_range is provided, it will take precedence

​
delta_from_ts
integer

The starting unix time in milliseconds for which to query data for delta comparison. Either delta_time_range or both delta_from_ts and delta_to_ts can be provided if delta is enabled. If delta_time_range is provided, it will take precedence.

​
delta_to_ts
integer

The ending unix time in milliseconds for which to query data for delta comparison. Either delta_time_range or both delta_from_ts and delta_to_ts can be provided if delta is enabled. If delta_time_range is provided, it will take precedence.

Response

Successfully retrieved usage metrics

​
id
string
required
Example:

"550e8400-e29b-41d4-a716-446655440000#home#usage"

​
name
string
required
Example:

"Usage"

​
filter
string
required
Example:

"resource='search'"

​
stat
string
required
Example:

"p90"

​
key
string
required
Example:

"duration_millis"

​
total_count
integer
required
Example:

58351920

​
total_value
number
required
Example:

18911006109

​
series
object[]
required

timeseries for non-group by queries

​
group_keys
string[]

Keys used for grouping the metric results

​
logs
string<uuid>[]
Example:
["41521f35-1b06-41f0-9cdc-9a938b5739d1"]
​
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.

Required array length: 1 - 50 elements
Required string length: 1 - 250
Example:
["environment:production"]
​
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'"

​
aux
object

Auxiliary data for the metric

Example:
{ "region": "us-west-1", "service": "s3" }
​
total_quantiles
object

Statistical distribution of the metric values 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
}
​
aggregates
object[]
​
is_exact
boolean

true if the series result is exact, false if it is an approximation

Example:

true

​
groups_series
object[]

timeseries for group by queries

​
delta
object

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