openapi: 3.2.0 info: description: '# Introduction This API is documented using the **OpenAPI 2.0** specification.' title: Logz.io Search logs API termsOfService: https://logz.io/about-us/terms-of-use/ contact: email: help@logz.io url: https://docs.logz.io/ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.logz.io/ security: - X-API-TOKEN: [] tags: - name: Search logs description: 'Use the Elasticsearch Search API DSL query language to search your Logz.io data. To ensure system performance and data availability, we''ve introduced some limitations to the original Elasticsearch specification. These limitations are detailed in the applicable API calls below.' paths: /v1/search: post: operationId: search summary: Search logs description: 'Searches your account data using the Elasticsearch Search API DSL query language. **total:** This call returns up to 1,000 results per query for aggregated results, or 10,000 results for non-aggregated results. **Note:** To ensure speed and availability of your logs, we restrict some options from the Elasticsearch defaults that could hamper system performance. Restrictions are described with their respective elements below. Please ensure to change the region in the URL to match your account''s region.' tags: - Search logs responses: 200: description: successful query. `hits` are the total number of logs that match the query, which will always be in the 0-2 day range. `total` are the actual logs that are returned when using the query, which are not limited by the selected time range. content: application/json: schema: type: object example: "{\n \"hits\": {\n \"total\": 339604,\n \"max_score\": 0.0,\n \"hits\": [ ]\n },\n \"aggregations\": {\n \"byType\": {\n \"doc_count_error_upper_bound\": 0,\n \"sum_other_doc_count\": 44879,\n \"buckets\": [\n {\n \"key\": \"web-app\",\n \"doc_count\": 163690\n },\n {\n \"key\": \"core-service\",\n \"doc_count\": 64893\n }\n ]\n }\n }\n}" requestBody: content: application/json: schema: type: object required: - query properties: query: type: object description: "The query can take any of the parameters described in the [Elasticsearch Search API DSL documentation](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search.html) with the exceptions stated below.\n#### Limitations\n* When using `query_string`, `allow_leading_wildcard` must be set to `false`\n* `wildcard` can't start with `*` or `?`\n* Can't contain `fuzzy_max_expansions`, `max_expansions`, or `max_determinized_states`\n#### Notes on the search time range\n* By default, your query runs on data sent today and yesterday, UTC.\n You can move this 2-calendar-day window by using the `dayOffset` query parameter.\n\n* Searches without a `timestamp` filter will return the last 2 calendar days, UTC.\n You can search other calendar days (up to 2 at a time) using a filter on the `timestamp`." example: bool: must: - range: '@timestamp': gte: now-5m lte: now from: type: integer minimum: 0 default: 0 description: Of the results found, the first result to return. example: 0 size: type: integer description: Number of results to return default: 10 maximum: 10000 example: 10 sort: type: array description: '#### Limitations * Can''t sort or aggregate on analyzed fields, such as the `message` field' items: type: object _source: type: object description: 'The object `includes` specifies an array of strings specifying an array of fields to return. * If you omit `_source` from the request, all fields are returned. * If you pass `''_source'': false`, it will exclude the `_source` field from the results.' properties: includes: type: array description: Array of fields to return example: - message items: type: string example: false post_filter: type: object description: A filter applied after the aggregations have been calculated. Useful for reusing a single query to calculate several outputs with different filtering criteria. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-request-post-filter.html) for details. example: null docvalue_fields: type: array description: Powers inverted indexing. Allows queries to look up the search term in unique sorted list by @timestamp. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-request-docvalue-fields.html) for details. items: type: string example: - '@timestamp' version: type: boolean description: Returns a version for each result. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-request-version.html) for details. stored_fields: type: array description: Useful for querying for fields that don’t appear in the _source field or querying for larger documents by date or title. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-request-stored-fields.html) for details. items: type: string example: - '*' highlight: type: object description: Highlight strings in one or more fields in your search results. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-request-highlighting.html) for details. aggregations: type: object description: 'Apply field aggregations. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-aggregations.html) for details. #### Limitations * When using the `size` element, the value must be ≤ `1000` * Can''t nest 2 or more bucket aggregations of these types: `date_histogram`, `geohash_grid`, `histogram`, `ip_ranges`, `significant_terms`, `terms` * Can''t sort or aggregate on analyzed fields, such as the `message` field * Aggregation type `significant_terms` and `multi_terms` can''t be used **Note:** You can use `aggs` or `aggregations` as the field name' example: byType: terms: field: type size: 5 required: true /v1/scroll: post: summary: Scroll logs tags: - Search logs description: 'This endpoint can take 2 types of call requests. The first type runs a search query that returns a `scrollID` and the first batch of paginated results. The second request type passes only the `scroll_id` (The variation in the field name is intentional) to fetch the next batches of paginated results. This endpoint always returns results as a stringified JSON. How it works: First, send a request to establish the `scrollID`. This initial request contains the query object and additional parameters, similar to the `v1/search` endpoint, with the exception that `dayOffset` and `accountIds` are not supported. The request will return the field `scrollId` and the number of `hits`, representing the number of matching results. For example, the `scroll_Id` string may have a value `*************80Y1JVcldDaVEAAAAAjeoh8hZYNkVkXzNhWVJRaUIwcWF5TEVnU2ZR`. Next, send the `scroll_id` in the request body to retrieve the log results as a stringified JSON. Each call returns the next page, where each page can return a maximum of 1000 results. Every time you resend the same `scroll_id` in the request body, it returns the next page until it reaches the end of the results. Note that ''scrollID'' expires after 20 minutes. Every time you send the request with the same `scroll_id`, the next batch of results is returned. Keep sending the same scroll ID as many times as needed to retrieve all of the available results. The results are paginated, and every request returns the next page, one at a time. When the call returns an empty array, you''ll know you''ve reached the end of your results. Note that the Scroll API is limited to searching only within the account associated with the token used. If the token belongs to the main account, the search will be limited to it and will not include sub-accounts. **Note**: * Send the field `scroll_id` in requests (snake_case). * Receive the field `scrollID` in your responses (camelCase). It expires after 20 minutes. Please ensure to change the region in the URL to match your account''s region.' operationId: scroll responses: 200: description: successful operation. `hits` are the total number of logs that match the query, which will always be in the 0-2 day range. `total` are the actual logs that are returned when using the query, which are not limited by the selected time range. content: application/json: schema: $ref: '#/components/schemas/ScrollResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/ScrollRequest' components: schemas: ScrollRequest: type: object properties: query: type: object description: 'Add a search query to receive the `scrollID` in the result. The query can take any of the parameters described in the [Elasticsearch Search API DSL documentation](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search.html) with the exceptions stated below. You can only add the `query` parameters if you are not passing the `scroll_id` in the request. #### Limitations * The query can only run on 2 consecutive indexes. By default, the query runs on data sent today and yesterday. You can also add a filter on `timestamp` to search a smaller time frame. * When using `query_string`, `allow_leading_wildcard` must be set to `false` to disable leading wildcards. In other words, the query can''t start with `*` or `?` * Can''t use `fuzzy_max_expansions`, `max_expansions`, or `max_determinized_states`' size: type: integer format: int32 description: Number of results to return default: 10 maximum: 1000 example: 50 from: type: integer format: int32 minimum: 0 description: Of the results found, the first result to return. example: 0 sort: type: array items: type: object description: '#### Limitations * Can''t sort on analyzed fields, such as the `message` field' _source: type: object description: 'The object `includes` specifies an array of strings specifying an array of fields to return. * If you omit `_source` from the request, all fields are returned. * If you pass `''_source'': false`, it will exclude the `_source` field from the results.' properties: includes: type: array description: Array of fields to return items: type: string example: - message post_filter: type: object scroll: type: string description: "These time units are supported:\n\n \n \n \n \n \n \n
UnitDescription
mminutes
sseconds
msmilliseconds
microsmicroseconds
nanosnanoseconds
\n\n#### Limitations\n* Time search must be ≤ 5 minutes. If no time is specified, default is `1m` (1 minute)." aggregations: type: object description: 'Apply field aggregations. See the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/search-aggregations.html) for details. #### Limitations * When using the `size` element, the value must be ≤ `1000` * Can''t nest 2 or more bucket aggregations of these types: `date_histogram`, `geohash_grid`, `histogram`, `ip_ranges`, `significant_terms`, `terms` * Can''t sort or aggregate on analyzed fields, such as the `message` field * Aggregation type `significant_terms` and `multi_terms` can''t be used * If the request specifies aggregations, only the initial search response will contain the aggregations results **Note:** You can use `aggs` or `aggregations` as the field name' example: byType: terms: field: type size: 5 ScrollResponse: type: object properties: code: type: integer format: int32 readOnly: true example: 200 scrollId: type: string readOnly: true description: Keep passing this ID in the request until you've retrieved all of the results. Copy this ID and pass it as the field `scroll_id` in a request to the same endpoint to retrieve the next page of results. (Remember to first clear the request body of all other parameters. The `scrollId` is valid for 20 minutes.) example: DnF1ZXJ5VGhlbkZldGNoCQAAAAAWXRbqFlNpSWRrTUtXUUR1N1pJbG9uSkJINncAAAAAFp6B-xZTTVFrMGt4eVFnZXhQZV9YbVRrU3NnAAAAABakA8QWNjY1RUZtdWZRS1NZZWt1ZERTNHNaQQAAAAAWXRbrFlNpSWRrTUtXUUR1N1pJbG9uSkJINncAAAAAFl0W7BZTaUlka01LV1FEdTdaSWxvbkpCSDZ3AAAAABQ1nb4WVjRyRlUxZWRUU0dzbTV5VVVqYkhxdwAAAAAUdHVqFlF0b3Znei1ZUXgtZEkyZkR3M0pMbGcAAAAAFvGs6hZKVklxaXIyZ1NOQzF5NHg1cmhtVDV3AAAAABR0dWkWUXRvdmd6LVlReC1kSTJmRHczSkxsZw== hits: type: string readOnly: true description: Query results in stringified JSON format. 'hits' are the total number of logs that match the query. securitySchemes: X-API-TOKEN: description: 'You can manage your API tokens from the [Logz.io API tokens](https://app.logz.io/#/dashboard/settings/manage-tokens/api) page. API tokens are account-specific. You will need to be logged into the relevant Log Management or SIEM account to view the API tokens associated with it. To manage your API tokens, log into the relevant account in your Logz.io platform, click the gear in the top-right menu, and select [**Tools > Manage tokens > API tokens**](https://app.logz.io/#/dashboard/settings/manage-tokens/api). It''s important to keep your tokens secure. API tokens carry privileges to make changes to users and accounts, so if you believe an API token has been compromised, delete it, and replace it with a new token in your integrations.' type: apiKey in: header name: X-API-TOKEN x-servers: - url: https://api.logz.io description: US East (Northern Virginia) - url: https://api-au.logz.io description: Asia Pacific (Sydney) - url: https://api-ca.logz.io description: Canada (Central) - url: https://api-eu.logz.io description: Europe (Frankfurt) - url: https://api-uk.logz.io description: Europe (London) x-tagGroups: - name: Log Monitoring tags: - Search logs - Alerts - Deployments - Insights - Logz.io snapshots - name: Cloud SIEM tags: - Security account - Security rules - Security events - Lookup lists - name: Account administration tags: - Manage users - Manage metrics account - Associated accounts - Authentication groups - Who am I - Manage time-based log accounts - Manage shared tokens - Manage API tokens - Manage notification endpoints - Import or export Kibana objects - name: Manage data shipping tags: - Manage log shipping tokens - Drop filters - Archive logs - Restore logs - Parsing - Delete object API - name: Data security tags: - Retrieve audit trail - name: Connect to AWS resources tags: - Connect to CloudTrail - Connect to S3 Buckets - name: Metrics API Gateway tags: - Grafana contact points - Grafana data source - Grafana alerting provisioning - Grafana silence management - Grafana annotations - Grafana dashboards - Grafana dashboard search - Grafana snapshots - Grafana get all folders description: Metrics API Gateway to supported endpoints.