> ## 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. # Get asynchronous search status > Poll the status, progress, and partial results of an asynchronous Bronto search query by its status identifier to track long-running search jobs. ## OpenAPI ````yaml get /search/status/{statusId} 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: /search/status/{statusId}: parameters: - name: statusId in: path description: The status id for the query. required: true schema: minItems: 1 type: string example: 92481b0a-d969-4ccd-b18d-00bc95694fe2 get: tags: - search summary: Poll a Query In Progress description: > Bronto provides an async API for long-running queries, which allows users to poll an in-progress query to monitor its progress and to receive partial results. It also allows an API client to handle multiple requests concurrently without blocking, and is more tolerant of network failures since a query will continue to execute if a connection is broken. Additionally it allows clients to cancel requests they are no longer interested in. For extremely long running queries it helps avoid issues due to timeouts. When the client makes an async query request, the server will initially respond with either a `201` or a `202` response code. The `201` response code is returned if the query was very short and the results are immediately available. Otherwise, if the query has started and is in-progress, the server will return a `202` response code and the response body will contain a status endpoint link (`/search/status/`) which should be polled periodically. When polled, the server will continue to respond with a `202` response code if the query is still in-progress, or it will respond with a `201` response code if the query has completed. The link must be polled at least once every 1 minute, otherwise the query will be cancelled. Once a query is completed the results can be retrieved using the status endpoint for at least 5 minutes, and up to 7 days (if the query results have expired the server will respond with a `410` response code). operationId: getSearchStatus responses: '200': description: In progress query. headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: status: type: string description: > The current status of the query. Possible value: * `COMPLETED` - the query finished successfully. * `IN_PROGRESS` - the query is still running. * `CANCELLED_BY_USER` - the query was stopped as a result of a `DELETE` request being issued. * `TIMED_OUT` - the query was stopped as it was not polled in time (as indicated by the `Retry-After` header in the response for the initial search request, or last poll). * `INTERNAL_SERVER_ERROR` - the query failed due to internal server error. example: IN_PROGRESS progress: type: integer description: >- A value between 0 and 100 indicating how much of the processing has finished. example: 56 start_time: type: string description: >- The time the query was started at, in human readable format. example: Tue Aug 06 15:24:15 GMT 2024 explain: $ref: '#/components/schemas/QueryExplain' result: type: array items: $ref: '#/components/schemas/QueryResult' events: type: array items: $ref: '#/components/schemas/Event' groups: type: array items: $ref: '#/components/schemas/Group' groups_series: type: array items: $ref: '#/components/schemas/GroupSeriesItem' metadata: $ref: '#/components/schemas/QueryMetadata' totals: type: object pagination: $ref: '#/components/schemas/Pagination' links: $ref: '#/components/schemas/SearchInProgressLinks' '201': description: Completed query results. 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 properties: status: type: string description: > The current status of the query. Possible value: * `COMPLETED` - the query finished successfully. * `IN_PROGRESS` - the query is still running. * `CANCELLED_BY_USER` - the query was stopped as a result of a `DELETE` request being issued. * `TIMED_OUT` - the query was stopped as it was not polled in time (as indicated by the `Retry-After` header in the response for the initial search request, or last poll). * `INTERNAL_SERVER_ERROR` - the query failed due to internal server error. example: COMPLETED progress: type: integer description: >- A value between 0 and 100 indicating how much of the processing has finished. example: 100 start_time: type: string description: >- The time the query was started at, in human readable format. example: Tue Aug 06 15:24:15 GMT 2024 explain: $ref: '#/components/schemas/QueryExplain' result: type: array items: $ref: '#/components/schemas/QueryResult' events: type: array items: $ref: '#/components/schemas/Event' groups: type: array items: $ref: '#/components/schemas/Group' groups_series: type: array items: $ref: '#/components/schemas/GroupSeriesItem' metadata: $ref: '#/components/schemas/QueryMetadata' totals: type: object pagination: $ref: '#/components/schemas/Pagination' links: $ref: '#/components/schemas/SearchCompletedLinksAsyncEnabled' '400': description: Bad Request - The body in the request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found - The status with given ID does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: This resources no longer exists. 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 Retry-After: description: > The maximum number of seconds that should pass before the next polling request on `/search/status/`. Returned only for `IN_PROGRESS` queries. You can issue requests to `/search/status/` more frequently than indicated in this header, however if no requests are made within that time, then the query will be stopped and the status will be reported as `TIMED_OUT`. schema: type: integer example: 45 schemas: QueryExplain: type: object properties: Execution time (millis): type: string description: Measure of time taken to execute the query. example: '353' QueryResult: type: object properties: '@time': type: string description: Human readable timestamp of when this log event was ingested example: 2024-03-27 10:25:40.632 UTC '@sequence': type: string description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: '111721913' '@raw': type: string description: 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" '@context': type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both metadata: type: object properties: logId: type: string description: The unique identifier of the log this log event came from format: uuid timestamp: type: integer description: The timestamp of when this log event was ingested example: 1711535140632 sequence: type: integer description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: 111721913 origin: type: string description: The identity of the sender if this log event. example: 10.0.0.1 context: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both selectedKeys: type: object description: The selected columns displayed in this result example: '@time': 2024-03-27 10:25:40.632 UTC unselectedKeys: type: object description: The available columns not displayed in this result example: id: message_0 current_time: 1711535140 links: type: array items: anyOf: - type: object properties: rel: type: string description: context example: context href: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both Event: type: object properties: '@raw': type: string description: 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" '@time': type: string description: > 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 '@status': type: string description: > 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 message_kvs: type: object description: Key-value pairs extracted from the log message example: method: GET statusCode: '200' path: / attributes: type: object description: > 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 metadata: type: object properties: service_id: type: string description: The unique identifier of the service this event came from. format: uuid example: 23746675-7022-4985-bd74-4af9eba58d72 timestamp: type: integer description: Unix timestamp in milliseconds of when this event was ingested. example: 1716853347801 sequence: type: integer description: >- The sequence number of this log event. Note sequence numbers are only unique within a millisecond timestamp. example: 111721913 context: type: string description: >- A url that can be used to get the events before and after this event. format: uri example: > "https://api.eu.bronto.io/context?sequence=213&from=37bdf479-7c95-4e81-982a-25d0680fb602×tamp=1716853354331&direction=both" description: The metadata of the event links: type: array items: anyOf: - type: object properties: rel: type: string description: next example: context href: type: string description: >- A url that can be used to get the log events before and after this log event. format: uri example: >- https://api.bronto.io/context?sequence=111721913&limit=1&from=23746675-7022-4985-bd74-4af9eba58d72×tamp=1711535140632&direction=both Group: type: object properties: group: type: string description: The groupby key or keys used by this group example: '[US]' 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(bytes) value: type: number description: Overall value of the statistical function applied format: double example: 50325.25 timeseries: type: array items: $ref: '#/components/schemas/GroupTimeSeries' 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' QueryMetadata: type: object properties: select: type: array description: >- The columns that were selected in the query request, and which appear in the results table. example: - host - status - method items: type: string correlation_id: type: string description: | The identifier which uniquely identifies this query. example: 00000000-0000-0000-0000-000000000000 Pagination: type: object properties: next_page_url: type: string description: The url to fetch the next set of results format: uri SearchInProgressLinks: type: array items: anyOf: - type: object properties: rel: type: string description: status example: status href: type: string description: >- The URL to fetch the query's status. See more information about the async api [here](#tag/search/operation/getSearchStatus). format: uri SearchCompletedLinksAsyncEnabled: type: array items: anyOf: - type: object properties: rel: type: string description: next example: next href: type: string description: >- For paginated event search queries, the URL which can be used to fetch the next page of results. format: uri - type: object properties: rel: type: string description: status example: status href: type: string description: >- The URL to fetch the query's status. See more information about the async api [here](#tag/search/operation/getSearchStatus). format: uri 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 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 ````