Logz.io Search logs API

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<table>\n  <thead><th>Unit</th><th>Description</th></thead>\n  <tr><td><code>m</code></td><td>minutes</td></tr>\n  <tr><td><code>s</code></td><td>seconds</td></tr>\n  <tr><td><code>ms</code></td><td>milliseconds</td></tr>\n  <tr><td><code>micros</code></td><td>microseconds</td></tr>\n  <tr><td><code>nanos</code></td><td>nanoseconds</td></tr>\n</table>\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.