Logs Query API

Overview

Last9 provides a powerful API for querying logs from your services. This document explains how to use the Logs Query API to search and retrieve logs programmatically.

The Logs Query API is LogQL and Loki compatible. For list of supported functions and parsers, refer to this.

API Access

You can find necessary credentials in the OpenTelemetry integration page.

Endpoint

The endpoint for querying logs is:

GET /loki/logs/api/v2/query_range

API Host

The API host is the same as your Last9 OpenTelemetry endpoint. For example:

https://otlp.last9.io
https://otlp-aps1.last9.io

Authentication

The API requires basic authentication using your organization credentials:

$last9_username: OTLP username
$last9_password: OTLP password

Query Parameters

The endpoint accepts the following parameters:

Parameter	Description	Example
`query`	The LogQL query to search for logs	`{service="api-gateway"}`
`start`	The start time of the query in Unix timestamp	`1743500000`
`end`	The end time of the query in Unix timestamp	`1743510000`
`limit`	The maximum number of logs to return	`100`

Example Queries

Basic Query

This example queries logs from a service named “api-gateway” with a limit of 100 results:

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%7D&start=1743500000&end=1743510000&limit=100' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

Note: The query parameter is URL-encoded. {service="api-gateway"} becomes %7Bservice%3D%22api-gateway%22%7D.

With Text Search

This example searches for logs containing the word “error” from a specific service:

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%7D%20|%3D%20%22error%22&start=1743500000&end=1743510000&limit=50' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

With Multiple Labels

This example queries logs with multiple label conditions:

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22payment-service%22%2C%20env%3D%22production%22%7D&start=1743500000&end=1743510000&limit=100' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

Response Format

A successful response will return a JSON object with the following structure:

{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": [
      {
        "stream": {
          "service": "api-gateway",
          "level": "info",
          "env": "production"
        },
        "values": [
          ["1743505000000000000", "Log message 1"],
          ["1743504990000000000", "Log message 2"],
          ["1743504980000000000", "Log message 3"]
        ]
      }
    ],
    "stats": {
      "summary": {
        "bytesProcessedPerSecond": 1048576,
        "linesProcessedPerSecond": 500,
        "totalBytesProcessed": 2097152,
        "totalLinesProcessed": 1000,
        "execTime": 0.25
      }
    }
  }
}

If no logs are found, the result field will be null:

{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": null,
    "stats": {
      "summary": {
        "bytesProcessedPerSecond": 0,
        "linesProcessedPerSecond": 0,
        "totalBytesProcessed": 0,
        "totalLinesProcessed": 0,
        "execTime": 0
      }
    }
  }
}

Advanced Usage

Discovering Services

To discover what service names are available in your logs, you can use the label values API:

curl -X GET 'https://otlp.last9.io/loki/logs/api/v1/label/service/values?start=1743000000&end=1743600000' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

This will return a list of all service names that have logs in the specified time range.

Time Range Conversion

Unix timestamps can be generated using various tools:

Current time: date +%s
Time from 1 hour ago: date -d "1 hour ago" +%s
Converting a specific date: date -d "2025-04-01 12:00:00" +%s

Querying From Specific Indices

By default, the API queries the default index. To query logs from a specific index, use the index parameter with the appropriate prefix:

For Physical Indices

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%7D&start=1743500000&end=1743510000&limit=100&index=physical_index:Pt_prod_k8s' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

For Rehydration Indices

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%7D&start=1743500000&end=1743510000&limit=100&index=rehydration_index:Rh_prod_archive' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

The format for the index parameter is:

physical_index:<index_name> for physical indices
rehydration_index:<index_name> for rehydration indices

Filtering by Log Level

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%2C%20level%3D%22error%22%7D&start=1743500000&end=1743510000&limit=100' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

RegEx Queries

curl -X GET 'https://otlp.last9.io/loki/logs/api/v2/query_range?query=%7Bservice%3D%22api-gateway%22%7D%20|~%20%22error.*timeout%22&start=1743500000&end=1743510000&limit=100' \
  -H 'Authorization: Basic $(echo -n $last9_username:$last9_password | base64)'

Rate Limiting

Be aware that the API may have rate limits to prevent abuse. If you’re making frequent queries, consider implementing backoff strategies in your application.

Debugging Common Scenarios

No Data Returned

If your query returns no data ("result": null), check the following:

Service name: Verify the service name is correct. Service names are case-sensitive and must match exactly.
Time range: Ensure your start and end timestamps cover a period where logs exist.
Data retention: Check if the queried time range is within your organization’s data retention period.
Query syntax: Make sure your LogQL query is correctly formatted and URL-encoded.

Invalid LogQL Error

If you receive {"detail":"parse error: invalid LogQL"}, check:

URL encoding: Ensure all special characters in your query are properly URL-encoded.
Query syntax: Verify that your LogQL query follows the correct syntax.
Quotation marks: Make sure all quotation marks in your query are properly escaped.

Parsing Time Range Error

If you receive {"detail":"parsing time range"}, ensure:

Valid timestamps: Confirm that your start and end parameters are valid Unix timestamps.
Chronological order: The start timestamp must be earlier than the end timestamp.
Required parameters: Some API endpoints require both start and end parameters even for non-time-specific queries.

Authorization Issues

If you receive authentication errors:

Credentials: Verify your organization name and basic auth key are correct.
Base64 encoding: Ensure the authorization header is properly formatted with correct Base64 encoding.
API access: Confirm your organization has access to the logs API.

Troubleshooting

Please get in touch with us on Discord or Email if you have any questions.