> ## 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 the top keys and sample values for a metric > Returns the keys (attributes) received for a metric within a time window, together with each key's data type and a sample of the values seen for it. Use this to discover which dimensions you can filter or group a metric by. Set the time window in one of two ways: - `time_range`, a relative range such as `last 20 minutes`, **or** - `from_ts` and `to_ts` together, as an absolute range in Unix milliseconds. If no time window is provided, the most recent keys and values are returned. The response is an object keyed by key name. Values are a sample, not an exhaustive list. ## OpenAPI ````yaml https://s3.eu-west-1.amazonaws.com/docs.brontobytes.io/redocusaurus/brontobytes.yaml get /metrics/{metric_id}/top-keys 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: collections description: > Collections group datasets together. Each collection contains one or more datasets. - name: datasets description: > Datasets are a sequence of timestamped log events. Datasets can be searched to view events matching a filter or to perform statistical functions on matching events. - 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.bronto.io/query-syntax/overview - 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: significant-keys description: > Significant-Keys is a REST API resource for the stored, model-ranked keys of a log or of a set of metrics: which fields are worth charting, the golden signal each serves, and the metrics worth building on them. Rankings are current state, not history. - 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. - name: config_assistant description: > The Config Assistant APIs provide endpoints for creating or modifying observability agent configurations. - name: patterns description: > Patterns return the Pattern IDs, templates, and source log ID for all logs matching the given search criteria. - name: metrics description: > Metrics are numeric time series ingested into Bronto, for example from OpenTelemetry collectors or SDKs. The Metrics endpoints return the metadata Bronto stores for each ingested metric, such as its name, type, unit and aggregation temporality, along with the keys and values received for it. They don't return datapoints. To query metric data, use the Timeseries API. - name: metric-definitions description: > Metric definitions are saved sets of queries and formulas that can be attached to widgets, monitors and SLOs. To compute a time series from a metric definition, use the Timeseries API. - name: timeseries description: > The Timeseries API computes time series and aggregations over log, trace and metric data. Use it to query the values of an ingested metric or to evaluate a metric definition. - name: audit description: > Bronto records audit events for actions taken in your account. The audit event schemas describe the structure of every audit event type. paths: /metrics/{metric_id}/top-keys: get: tags: - metrics summary: Retrieve the top keys and sample values for a metric description: > Returns the keys (attributes) received for a metric within a time window, together with each key's data type and a sample of the values seen for it. Use this to discover which dimensions you can filter or group a metric by. Set the time window in one of two ways: - `time_range`, a relative range such as `last 20 minutes`, **or** - `from_ts` and `to_ts` together, as an absolute range in Unix milliseconds. If no time window is provided, the most recent keys and values are returned. The response is an object keyed by key name. Values are a sample, not an exhaustive list. operationId: getTopKeysForMetric parameters: - name: metric_id in: path description: The unique identifier (UUID) of the metric. required: true schema: type: string format: uuid example: 41521f35-1b06-41f0-9cdc-9a938b5739d1 - name: time_range in: query description: | The relative time range for which to retrieve the keys. schema: type: string example: last 20 minutes - name: from_ts in: query description: >- The starting time (unix time in milliseconds) for which retrieve the keys. Must be used together with `to_ts`. This parameter is incompatible with `time_range`. schema: type: integer format: int64 example: 1709251200000 - name: to_ts in: query description: >- The ending time (unix time in milliseconds) for which to retrieve the keys. Must be used together with `from_ts`. This parameter is incompatible with `time_range`. schema: type: integer format: int64 example: 1711390455601 responses: '200': description: Metric keys retrieved successfully headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/TopKeysPerLogOrMetric' example: Resource:service.name: type: STRING field_type: ATTRIBUTE values: checkout: value: checkout payments: value: payments Resource:host.name: type: STRING field_type: ATTRIBUTE values: ip-10-0-1-23: value: ip-10-0-1-23 cpu: type: NUMBER field_type: ATTRIBUTE values: '0': value: '0' '1': value: '1' '404': description: >- Not Found - The metric keys were not found, review the metric id or the time range content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unexpected_error: summary: Unexpected error value: code: 500 type: Internal Server Error correlation_id: b129b8e0e66c41aa9541a30f67e38ce2 details: Internal Server Error 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: TopKeysPerLogOrMetric: required: - type type: object properties: rank: type: integer description: >- A count representing the number of times this key was in the sampled data. example: 5 deprecated: true type: type: string description: A description of the type of data contained in the key. enum: - STRING - NUMBER - BOOLEAN field_type: type: string description: A description of the source of the given key. enum: - ATTRIBUTE - MESSAGE_KVP values: type: object additionalProperties: $ref: '#/components/schemas/TopKeyValue' description: a sample list of values ErrorResponse: required: - code - correlation_id - details - type type: object properties: code: maximum: 599 minimum: 400 type: integer description: HTTP status code for the error response. format: int32 type: type: string description: >- HTTP reason phrase associated with the status code (e.g. "Not Found" for 404) example: Not Found correlation_id: type: string description: Unique identifier for the request, used for tracing and debugging. details: type: string description: Human-readable description of the error. example: Resource not found. description: Standard error response returned by the API when a request fails. example: code: 404 type: Not Found correlation_id: 605f832bcfe44a1081441691c8d42253 details: Resource not found. TopKeyValue: type: object properties: value: type: string description: A value associated with the key. rank: type: integer description: >- A count representing the number of times a value occurred for the key. deprecated: true securitySchemes: ApiKeyAuth: type: apiKey name: X-BRONTO-API-KEY in: header BearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.