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>'
import requests

url = "https://api.eu.bronto.io/usage"

headers = {"X-BRONTO-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'X-BRONTO-API-KEY': '<api-key>'}};

fetch('https://api.eu.bronto.io/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.eu.bronto.io/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-BRONTO-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.eu.bronto.io/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-BRONTO-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.eu.bronto.io/usage")
  .header("X-BRONTO-API-KEY", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.eu.bronto.io/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-BRONTO-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "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
  }
}
{
  "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"
    }
  }
}
{
  "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"
    }
  }
}
{
  "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"
    }
  }
}
{
  "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"
    }
  }
}
{
  "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"
    }
  }
}

Authorizations

​
X-BRONTO-API-KEY
string
header
required

Query Parameters

​
time_range
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