DOCSEARCHbyAlgolia
Submit Docs

Logz.io API Documentation

website·Indexed 40 days ago

https://api-docs.logz.io/

API reference for Logz.io, providing endpoints for managing notification endpoints (Slack, PagerDuty, Datadog, OpsGenie, ServiceNow, Microsoft Teams, BigPanda), configuring drop filters, managing dashboards via the Perses API, exporting Kibana objects, and setting up log archiving.

Tokens
75.2K
Snippets
259
Records
517
Agent score
58%

What's inside Logz.io

  1. Understand Logz.io Insight types

    Logz.io monitors logs to identify potential problems through two primary Insight types:

    • LOGCEPTION: Identifies application errors and exceptions found within stack traces.
    • PUBLIC_CI: Cognitive Insights that correlate logs with trending vulnerabilities and issues in the open-source community.

  2. Use drop filters to reduce log indexing volume and costs

    Drop filters allow you to filter out logs before they are indexed in your Logz.io account. This is primarily used to lower costs and reduce account volume.

    Key behaviors include:

    • Matching: Filters evaluate logs for exact field:value matches.
    • Indexing: Logs that match an active drop filter are not indexed, meaning they will not appear in Kibana, will not be searchable, will not trigger alerts, and will not appear in dashboards.
    • Archiving: Drop filters do not affect archiving. If archiving is configured, dropped logs are still archived and can be restored if they become relevant later.

  3. Retrieve a specific metrics account by ID

    Retrieve detailed information about a specific metrics account, including its token, creation date, and UTS (Unique Time Series) plan limits. When making the request, ensure the region in the base URL matches the region associated with your account.

    Path Parameter:

    • metricsAccountId (string, required): The unique identifier of the metrics account.

    Response Schema (200 OK):

    • id (integer): ID of the metrics account.
    • accountName (string): Name of the metrics account.
    • token (string): Metrics account token.
    • createdAt (date-time): Timestamp of account creation.
    • planUts (integer): Usage plan for Unique Time Series (UTS). This defines the maximum number of unique time series allowed; data points exceeding this limit will not be processed.
    • authorizedAccountsIds (integer[]): A list of IDs for authorized accounts.
    GET /v1/account-management/metrics-accounts/{metricsAccountId}

  4. Understand Logz.io Cloud SIEM security events

    A security event is generated whenever a security rule triggers within a Logz.io Cloud SIEM account. These rules include a pre-loaded set maintained by Logz.io analysts as well as custom rules created by the user. To investigate these events, developers can use a two-step process: first, run a bulk query to fetch security event logs (with optional filtering), and second, perform a drilldown query to retrieve the specific logs that triggered the security event for deeper analysis. This workflow is typically used for security posture monitoring or integration with automated response solutions like Cortex xSOAR.

  6. Create and update dashboard folders using Perses documents

    To create or update a dashboard folder, you must provide a complete Perses project document in the request body. Note that the update operation replaces the entire stored document rather than merging changes; therefore, the full desired state must be sent. If the request body is not a complete Perses project document, the API returns a 400 error specifying the failed field. To change only the folder name without replacing the entire document, use the 'Rename dashboard folder' endpoint.

  7. Paginate through logs using the Scroll API

    The /v1/scroll endpoint allows you to retrieve large volumes of logs in paginated batches. The process consists of two phases: an initial request to establish a search context and subsequent requests to fetch the data pages.

    1. Initial Request: Send a POST request with a query object. The response will contain a scrollId and the first batch of results.
    2. Subsequent Requests: To retrieve the next page, send a POST request containing only the scroll_id (snake_case) in the request body.
    3. Completion: Continue sending the same scroll_id until the API returns an empty array, indicating all results have been retrieved.

    Key Constraints:

    • The scrollId expires after 20 minutes.
    • Each page returns a maximum of 1000 results.
    • The Scroll API is limited to the account associated with the authentication token; it does not include sub-accounts if the token belongs to the main account.
    • Results are returned as stringified JSON.
    // Initial Request Body
{
  "query": { "match": { "message": "error" } },
  "size": 1000
}

// Subsequent Request Body (to get next page)
{
  "scroll_id": "*************80Y1JVcldDaVEAAAAAjeoh8hZYNkVkXzNhWVJRaUIwcWF5TEVnU2ZR"
}

  8. Retrieve detailed information for all accounts

    Use the /v1/account-management/time-based-accounts/detailed endpoint to get detailed information for the main account and all associated sub-accounts. This includes usage data and sharing permissions for Kibana objects.

    Requirements:

    • Must be called using an API token from the main account.
    • The URL region must be updated to match the account's specific region.
    • The response is returned as an array of JSON objects, where each object represents a sub-account.
    GET /v1/account-management/time-based-accounts/detailed

  9. Retrieve a shared token by ID using the Logz.io API

    Use the GET /v1/shared-tokens/:id endpoint to retrieve a specific shared token's details as a JSON object.

    Important Requirements:

    • Permissions: This endpoint requires specific permissions that must be enabled by the Logz.io Support team. Contact help@logz.io to request access.
    • Regional URL: Ensure the base URL region matches the region where your account is hosted.

    Path Parameters:

    • id (int32, required): The unique ID of the shared token.

    Response Schema (200 OK):

    • id (int32): ID of the shared token.
    • name (string): Descriptive name of the token.
    • token (string): The actual token value.
    • filters (int32[]): Array of filter IDs attached to the token; returns null if no filters are attached.
    • lastUsed (int64[]): UNIX timestamp in milliseconds of the last usage; returns null if never used.
    • expirationDate (int64[]): UNIX timestamp in milliseconds of the expiration date; returns null if no expiration is set.
    • filtersOperator (string[]): The logical operator used to combine filters. Valid values are OR or AND.
    # Example request (replace {region} and {id} with your actual values)
curl -X GET "https://api.{region}.logz.io/v1/shared-tokens/{id}"

  10. Upload an external mapping file to Logz.io storage

    Upload a .properties format mapping file to Logz.io storage to be used by the Sawmill ExternalMappingSourceProcessor.

    Constraints and Requirements:

    • Enablement: This feature is not enabled by default; you must contact Logz.io support to enable it.
    • Limits: Maximum of 10 files per account.
    • File Size: Maximum file size is 50 MB.
    • Region: The API URL must be updated to match your specific account's region.

    API Endpoint:

    • Method: POST
    • Path: /v1/sawmill/external-mapping/upload
    • Content-Type: multipart/form-data

    Request Body:

    • file: The binary content of the .properties file.

    Responses:

    • 201: Successful operation. Returns a JSON object with a result string (e.g., "Successfully updated external mapping").
    • 400: Bad Request.
    • 422: Unprocessable Entity.

  11. Configure AI Agent (OrionIQ) analysis for alerts

    Enable AI-powered analysis for alerts using the following fields in the request body:

    • rca (boolean): Activate AI Agent analysis (OrionIQ).
    • runbook (string): Provide instructions to help the AI Agent understand how to handle the alert.
    • rcaNotificationEndpointIds (integer[]): Specific notification endpoints for AI analysis.
    • useAlertNotificationEndpointsForRca (boolean): If true, uses the standard alert notification endpoints for AI analysis.

  12. Manage Logz.io Dashboard versions and privacy

    Logz.io Dashboards handle versioning and privacy with the following behaviors:

    • Versioning: Every update creates a new version and increments the version field. While earlier versions are retained internally, they are not accessible via the API.
    • Private Dashboards: Dashboards marked as private in the Logz.io app are only visible to API tokens with admin permissions. For non-admin tokens, these dashboards are omitted from lists/searches and return a 404 error. Privacy settings cannot be modified via the API.