openapi: 3.1.0 info: title: openobserve Actions Search API description: OpenObserve API documents [https://openobserve.ai/docs/](https://openobserve.ai/docs/) contact: name: OpenObserve url: https://openobserve.ai/ email: hello@zinclabs.io license: name: AGPL-3.0 identifier: AGPL-3.0 version: 0.90.0 tags: - name: Search description: Search/Query operations paths: /api/{org_id}/_search: post: tags: - Search summary: Search data with SQL description: Executes SQL queries against log streams with support for complex search patterns, time range filtering, aggregations, and histogram generation. Supports advanced features like multi-stream searches, caching, and UI optimizations for dashboard visualizations. operationId: SearchSQL parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: type in: query description: 'Stream type. one of: logs, metrics, traces. Defaults to logs.' required: false schema: type: string - name: is_ui_histogram in: query description: 'Whether to return histogram data for UI (default: false)' required: false schema: type: boolean - name: is_multi_stream_search in: query description: 'Indicate is search is for multi stream (default: false)' required: false schema: type: boolean - name: validate in: query description: 'Validate query fields against stream schema and User-Defined Schema (UDS). When enabled, returns error if queried fields are not in schema or not allowed by UDS (default: false)' required: false schema: type: boolean requestBody: description: Search query content: application/json: schema: type: object required: - query properties: clear_cache: type: boolean clusters: type: array items: type: string encoding: $ref: '#/components/schemas/RequestEncoding' local_mode: type: - boolean - 'null' query: $ref: '#/components/schemas/SearchQuery' regions: type: array items: type: string search_event_context: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchEventContext' search_type: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchEventType' timeout: type: integer format: int64 use_cache: type: boolean example: query: sql: select * from k8s start_time: 1675182660872049 end_time: 1675185660872049 from: 0 size: 10 required: true responses: '200': description: Success content: application/json: schema: type: object example: took: 155 hits: - _p: F _timestamp: 1674213225158000 kubernetes: container_hash: dkr.ecr.us-west-2.amazonaws.com/openobserve@sha256:3dbbb0dc1eab2d5a3b3e4a75fd87d194e8095c92d7b2b62e7cdbd07020f54589 container_image: dkr.ecr.us-west-2.amazonaws.com/openobserve:v0.0.3 container_name: openobserve docker_id: eb0983bdb9ff9360d227e6a0b268fe3b24a0868c2c2d725a1516c11e88bf5789 host: ip.us-east-2.compute.internal namespace_name: openobserve pod_id: 35a0421f-9203-4d73-9663-9ff0ce26d409 pod_name: openobserve-ingester-0 log: '[2023-01-20T11:13:45Z INFO actix_web::middleware::logger] 10.2.80.192 "POST /api/demo/_bulk HTTP/1.1" 200 68' stream: stderr total: 27179431 from: 0 size: 1 scan_size: 28943 '400': description: Failure content: application/json: schema: default: null '500': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-mcp: description: 'Search data with SQL, you can use `match_all(''foo'')` to search with full text search, also you can use `str_match(field, ''bar'')` to search in a specific field; start_time, end_time can''t be zero, need to be a valid micro timestamp. Note: in summary mode, response is capped at 100 hits, request detail=''full'' if you need more.' category: search pinned: true x-o2-ratelimit: module: Search operation: get /api/{org_id}/_search_history: post: tags: - Search summary: Search query history description: Retrieves historical search queries and their execution details operationId: SearchHistory parameters: - name: org_id in: path description: Organization ID required: true schema: type: string requestBody: description: Search history request parameters content: application/json: schema: type: object description: Request parameters for querying search history required: - start_time - end_time properties: end_time: type: integer format: int64 description: end time in micro seconds org_id: type: - string - 'null' description: Organization ID to filter search history by size: type: integer format: int64 description: Maximum number of search history records to return start_time: type: integer format: int64 description: start time in micro seconds stream_name: type: - string - 'null' description: Name of the specific stream to filter by stream_type: type: - string - 'null' description: Type of stream to filter by (e.g., logs, metrics, traces) trace_id: type: - string - 'null' description: Trace ID to filter search history by user_email: type: - string - 'null' description: Email of the user to filter search history by example: stream_name: default stream_type: logs min_ts: 1632960000 max_ts: 1633046400 trace_id: 7f7898fd19424c47ba830a6fa9b25e1f size: 100 required: true responses: '200': description: Success content: application/json: schema: type: object example: took: 40 took_detail: total: 40 idx_took: 0 wait_in_queue: 0 hits: - cached_ratio: 0 end_time: 15 org_id: default scan_records: 1 scan_size: 7.0 sql: SELECT COUNT(*) from "default" start_time: 0 stream_name: default stream_type: logs took: 0.056222333 trace_id: 7f7898fd19424c47ba830a6fa9b25e1f function: . total: 3 from: 0 size: 20 cached_ratio: 0 scan_size: 0 idx_scan_size: 0 scan_records: 3 trace_id: 2lsPBWjwZxUJ5ugvZ4jApESZEpk is_partial: false result_cache_ratio: 0 '400': description: Bad Request - Invalid parameters or body content: application/json: schema: default: null '500': description: Internal Server Error content: application/json: schema: default: null security: - Authorization: [] x-o2-ratelimit: module: Search operation: get x-o2-mcp: description: Get search history category: search /api/{org_id}/_search_partition: post: tags: - Search summary: Search partition data description: Executes search queries on partitioned log data with specified parameters operationId: SearchPartition parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: type in: query description: 'Stream type. Must be one of: logs, metrics, traces. Defaults to logs if not specified.' required: false schema: type: string - name: enable_align_histogram in: query description: Enable align histogram required: true schema: type: boolean requestBody: description: Search query content: application/json: schema: type: object required: - sql - start_time - end_time properties: clusters: type: array items: type: string encoding: $ref: '#/components/schemas/RequestEncoding' end_time: type: integer format: int64 histogram_interval: type: integer format: int64 query_fn: type: - string - 'null' regions: type: array items: type: string sampling_ratio: type: - number - 'null' format: double sql: type: string start_time: type: integer format: int64 streaming_output: type: boolean example: sql: 'select * from k8s ' start_time: 1675182660872049 end_time: 1675185660872049 required: true responses: '200': description: Success content: application/json: schema: type: object example: took: 155 file_num: 10 original_size: 10240 compressed_size: 1024 partitions: - - 1674213225158000 - 1674213225158000 - - 1674213225158000 - 1674213225158000 '400': description: Failure content: application/json: schema: default: null '500': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-ratelimit: module: Search operation: get x-o2-mcp: description: Get search partitions then you can call _search api by partitions to give the result looks faster category: search /api/{org_id}/_search_stream: post: tags: - Search summary: Stream search results description: Executes a search query and streams the results back in real-time using HTTP/2 server-sent events. This is ideal for large result sets or long-running queries where you want to receive data as it becomes available rather than waiting for the complete response. Results are streamed as JSON objects separated by newlines. operationId: SearchStreamHttp2 parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: is_ui_histogram in: query description: Whether to return histogram data for UI required: true schema: type: boolean - name: is_multi_stream_search in: query description: Indicate is search is for multi stream required: true schema: type: boolean requestBody: description: Search query content: application/json: schema: type: string example: sql: select * from logs LIMIT 10 start_time: 1675182660872049 end_time: 1675185660872049 required: true responses: '200': description: Success content: text/event-stream: {} '400': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-ratelimit: module: Search operation: get x-o2-mcp: enabled: false /api/{org_id}/_values_stream: post: tags: - Search summary: Get field values with HTTP/2 streaming description: Retrieves field values from logs using HTTP/2 streaming for real-time results operationId: ValuesStreamHttp2 parameters: - name: org_id in: path description: Organization name required: true schema: type: string requestBody: description: Values query content: application/json: schema: type: string example: sql: select * from logs LIMIT 10 start_time: 1675182660872049 end_time: 1675185660872049 required: true responses: '200': description: Success content: text/event-stream: {} '400': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-ratelimit: module: Search operation: get x-o2-mcp: enabled: false /api/{org_id}/{stream_name}/_around: get: tags: - Search summary: Search around specific log entry description: Searches for log entries around a specific key (timestamp or record identifier) within a stream. Returns logs before and after the specified key, useful for investigating context around specific events or errors. operationId: SearchAround parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: stream_name in: path description: stream_name name required: true schema: type: string - name: type in: query description: 'Stream type. Must be one of: logs, metrics, traces. Defaults to logs if not specified.' required: false schema: type: string - name: key in: query description: around key required: true schema: type: integer format: int64 - name: size in: query description: around size required: true schema: type: integer format: int64 - name: regions in: query description: regions, split by comma required: false schema: type: string - name: timeout in: query description: timeout, seconds required: false schema: type: integer format: int64 responses: '200': description: Success content: application/json: schema: type: object example: took: 155 hits: - _p: F _timestamp: 1674213225158000 kubernetes: container_hash: dkr.ecr.us-west-2.amazonaws.com/openobserve@sha256:3dbbb0dc1eab2d5a3b3e4a75fd87d194e8095c92d7b2b62e7cdbd07020f54589 container_image: dkr.ecr.us-west-2.amazonaws.com/openobserve:v0.0.3 container_name: openobserve docker_id: eb0983bdb9ff9360d227e6a0b268fe3b24a0868c2c2d725a1516c11e88bf5789 host: ip.us-east-2.compute.internal namespace_name: openobserve pod_id: 35a0421f-9203-4d73-9663-9ff0ce26d409 pod_name: openobserve-ingester-0 log: '[2023-01-20T11:13:45Z INFO actix_web::middleware::logger] 10.2.80.192 "POST /api/demo/_bulk HTTP/1.1" 200 68' stream: stderr total: 10 from: 0 size: 10 scan_size: 28943 '500': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-ratelimit: module: Search operation: get x-o2-mcp: description: 'Search logs around a timestamp. Note: in summary mode, hits are capped at 100 and only hits/total/took/columns/scan_size/function_error are returned.' category: search post: tags: - Search summary: Search around specific log record description: Advanced version of around search that accepts a full log record in the request body instead of just a key. Searches for log entries around the specified record, providing better context matching based on the complete record data. operationId: SearchAroundV2 parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: stream_name in: path description: stream_name name required: true schema: type: string - name: size in: query description: around size required: true schema: type: integer format: int64 - name: regions in: query description: regions, split by comma required: false schema: type: string - name: timeout in: query description: timeout, seconds required: false schema: type: integer format: int64 requestBody: description: around record data content: application/json: schema: type: string example: _timestamp: 1675182660872049 container_image: dkr.ecr.us-west-2.amazonaws.com/openobserve:v0.0.3 container_name: openobserve docker_id: eb0983bdb9ff9360d227e6a0b268fe3b24a0868c2c2d725a1516c11e88bf5789 host: ip.us-east-2.compute.internal namespace_name: openobserve pod_id: 35a0421f-9203-4d73-9663-9ff0ce26d409 pod_name: openobserve-ingester-0 required: true responses: '200': description: Success content: application/json: schema: type: object example: took: 155 hits: - _p: F _timestamp: 1674213225158000 kubernetes: container_hash: dkr.ecr.us-west-2.amazonaws.com/openobserve@sha256:3dbbb0dc1eab2d5a3b3e4a75fd87d194e8095c92d7b2b62e7cdbd07020f54589 container_image: dkr.ecr.us-west-2.amazonaws.com/openobserve:v0.0.3 container_name: openobserve docker_id: eb0983bdb9ff9360d227e6a0b268fe3b24a0868c2c2d725a1516c11e88bf5789 host: ip.us-east-2.compute.internal namespace_name: openobserve pod_id: 35a0421f-9203-4d73-9663-9ff0ce26d409 pod_name: openobserve-ingester-0 log: '[2023-01-20T11:13:45Z INFO actix_web::middleware::logger] 10.2.80.192 "POST /api/demo/_bulk HTTP/1.1" 200 68' stream: stderr total: 10 from: 0 size: 10 scan_size: 28943 '500': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-mcp: enabled: false x-o2-ratelimit: module: Search operation: get /api/{org_id}/{stream_name}/_values: get: tags: - Search summary: Get distinct field values description: Retrieves the top N distinct values for specified fields within a stream and time range. Supports filtering, keyword search, and frequency counting. Essential for building dynamic filters, dropdowns, and understanding data cardinality in dashboards and analytics. operationId: SearchValues parameters: - name: org_id in: path description: Organization name required: true schema: type: string - name: stream_name in: path description: stream_name name required: true schema: type: string - name: type in: query description: 'Stream type. Must be one of: logs, metrics, traces. Defaults to logs if not specified.' required: false schema: type: string - name: fields in: query description: fields, split by comma required: true schema: type: string - name: filter in: query description: 'filter, eg: a=b' required: false schema: type: string - name: keyword in: query description: 'keyword, eg: abc' required: false schema: type: string - name: size in: query description: size required: true schema: type: integer format: int64 - name: from in: query description: from required: true schema: type: integer format: int64 - name: start_time in: query description: start time required: true schema: type: integer format: int64 - name: end_time in: query description: end time required: true schema: type: integer format: int64 - name: regions in: query description: regions, split by comma required: false schema: type: string - name: timeout in: query description: timeout, seconds required: false schema: type: integer format: int64 - name: no_count in: query description: no need count, true of false required: false schema: type: boolean responses: '200': description: Success content: application/json: schema: type: object example: took: 155 values: - field: field1 values: - value1 - value2 '400': description: Failure content: application/json: schema: default: null '500': description: Failure content: application/json: schema: default: null security: - Authorization: [] x-o2-mcp: description: Get distinct values for a field category: search x-o2-ratelimit: module: Search operation: get components: schemas: SearchEventType: type: string enum: - ui - dashboards - reports - alerts - values - other - rum - derivedstream - searchjob - download - insights SearchEventContext: type: object properties: alert_key: type: - string - 'null' alert_name: type: - string - 'null' dashboard_id: type: - string - 'null' dashboard_name: type: - string - 'null' derived_stream_key: type: - string - 'null' folder_id: type: - string - 'null' folder_name: type: - string - 'null' report_id: type: - string - 'null' RequestEncoding: type: string enum: - base64 - Empty SearchQuery: type: object required: - sql - start_time - end_time properties: action_id: type: - string - 'null' end_time: type: integer format: int64 from: type: integer format: int64 histogram_interval: type: integer format: int64 query_fn: type: - string - 'null' query_type: type: string quick_mode: type: boolean sampling_config: type: - object - 'null' sampling_ratio: type: - number - 'null' format: double description: 'Simplified sampling API: just specify ratio (0.0-1.0), backend uses optimal defaults Takes precedence over sampling_config if both are provided' size: type: integer format: int64 skip_wal: type: boolean sql: type: string start_time: type: integer format: int64 streaming_id: type: - string - 'null' streaming_output: type: boolean track_total_hits: type: boolean uses_zo_fn: type: boolean securitySchemes: Authorization: type: apiKey in: header name: Authorization BasicAuth: type: http scheme: basic