> ## 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. > Retrieve Bronto ingestion and search usage for a specific log dataset over a chosen timeframe to monitor costs, capacity, and billing trends per log ID. # Get the usage over a period of time for a log id. ## OpenAPI ````yaml get /usage/organizations/logs 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: /usage/organizations/logs: get: tags: - usage summary: Get the usage over a period of time for a log id. operationId: getUsageByLogId parameters: - name: time_range in: query description: > The relative time range for which to calculate usage data. Time range supported is from minutes to years. For an exact range, use `from_ts` and `to_ts` instead. schema: type: string examples: mins: value: Last 10 minutes day: value: Last 2 days week: value: Last 3 weeks - name: from_ts in: query description: >- The starting time (unix time in milliseconds) for which to calculate usage data. Must be used together with `to_ts`. This parameter is not to be used when using `time_range`. schema: type: integer example: 1709251200000 - name: to_ts in: query description: >- The ending time (unix time in milliseconds) for which to calculate usage data. Must be used together with `from_ts`. This parameter is incompatible with `time_range`. schema: type: integer example: 1711390455601 - name: usage_type in: query description: The type of usage to query. schema: type: string enum: - ingestion - search - export - name: limit in: query description: > Returns the top N logs based on the usage. If not provided, the default limit is 50. The maximum limit is 100. required: false schema: type: integer example: 10 - name: num_of_slices in: query description: > 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) required: false schema: type: integer example: 10 - name: delta in: query description: > 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. required: false schema: type: boolean example: true - name: delta_time_range in: query description: > 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 required: false schema: type: string example: '''Previous month'', ''Previous quarter'', ''This day last week''' - name: delta_from_ts in: query description: > 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. required: false schema: type: integer example: 1709251200000 - name: delta_to_ts in: query description: > 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. required: false schema: type: integer example: 1711390455601 responses: '200': description: Successful response headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/UsageByLogId' '400': description: Bad Request - The time range 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: 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 schemas: UsageByLogId: type: object properties: name: type: string example: Usage filter: type: string example: event_type='log_usage' stat: type: string example: SUM key: type: string example: bytes_total is_exact: type: boolean description: true if the series result is exact, false if it is an approximation example: true groups_series: type: array items: $ref: '#/components/schemas/GroupSeriesItem' 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 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' 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 securitySchemes: ApiKeyAuth: type: apiKey name: X-BRONTO-API-KEY in: header BearerAuth: type: http scheme: bearer bearerFormat: JWT ````