Logs API - Query and Analyze SigNoz Logs over HTTP

Overview

The SigNoz Logs API is a robust interface which enables developers to manage and analyze log data efficiently. This API facilitates various operations:

• Searching Logs: Allows users to search through log data based on specific criteria. For example, finding all logs where the error code is 500.

• Paginating Logs: Helps in navigating through large sets of log data in a manageable way. For instance, retrieving logs in batches of 100 for easy viewing.

• Aggregating Logs: Enables summarizing log data to extract meaningful insights, such as aggregating logs to count the number of errors per day.

API Endpoint

Endpoint for Logs API:

POST https://<your-instance-url>/api/v5/query_range

Replace <your-instance-url> with the URL of your SigNoz instance, for example example.us.signoz.cloud.

Prerequisites

API key: To access this API, you need an API key. Go to Settings → Service Accounts in SigNoz, create a service account, and generate an API key from its Keys tab. See Service Accounts for step-by-step instructions.

API keys can only be created/managed by users with the Admin role. If you don't have the Admin role, contact your organization's admin to create an API key for you.

The service account needs a role that can read logs, such as signoz-viewer. See Service Accounts.

SigNoz version: the steps on this page work on SigNoz Cloud and on self-hosted SigNoz v0.114.0 or later, the first version with service accounts.

Authentication

Using the API key: Add the API key to your request header as follows:

SIGNOZ-API-KEY: <your-api-key>

Send a Request

This example returns the 10 latest error logs from the last 15 minutes.

1. Set the URL of your SigNoz instance and your API key:

   Copy

   export SIGNOZ_URL="https://<your-instance-url>"
   export SIGNOZ_API_KEY="<your-api-key>"

   Verify these values:

   • <your-instance-url>: the URL that you use to open SigNoz, for example example.us.signoz.cloud on SigNoz Cloud or signoz.example.com for self-hosted SigNoz. If your self-hosted instance has no TLS, change https:// to http://.
   • <your-api-key>: the API key from Prerequisites.

2. Create the request payload. start and end are Unix timestamps in milliseconds:

   Copy

   END_MS=$(( $(date +%s) * 1000 ))
   START_MS=$(( END_MS - 15 * 60 * 1000 ))
    
   cat > query.json <<EOF
   {
     "start": $START_MS,
     "end": $END_MS,
     "requestType": "raw",
     "compositeQuery": {
       "queries": [
         {
           "type": "builder_query",
           "spec": {
             "name": "A",
             "signal": "logs",
             "filter": { "expression": "severity_text = 'ERROR'" },
             "order": [{ "key": { "name": "timestamp" }, "direction": "desc" }],
             "limit": 10
           }
         }
       ]
     }
   }
   EOF

3. Send the request:

   Copy

   curl -s -X POST "$SIGNOZ_URL/api/v5/query_range" \
     -H "SIGNOZ-API-KEY: $SIGNOZ_API_KEY" \
     -H "Content-Type: application/json" \
     -d @query.json

The response lists each log in data.data.results[0].rows. Each row has the log fields under data. This response is shortened:

{
  "status": "success",
  "data": {
    "type": "raw",
    "data": {
      "results": [
        {
          "queryName": "A",
          "rows": [
            {
              "timestamp": "2026-11-06T05:52:01.605786Z",
              "data": {
                "body": "payment gateway timeout for order 42",
                "severity_text": "ERROR",
                "resources_string": { "service.name": "checkout" },
                "attributes_string": { "http.route": "/api/checkout" },
                "trace_id": "",
                "id": "0mMZCp9dqBWc0v0QJnO2BRUhgst",
                "timestamp": 1793944321605786000
              }
            }
          ]
        }
      ]
    }
  }
}

To return only some fields, such as the log body, see Return only some fields.

If the response has the authz_forbidden error code, the service account of the API key has no role that can read logs. Assign it a role such as signoz-viewer.

Operations

• Search Logs — filter logs by attributes, body content, severity, or trace ID with pagination support.
• Aggregate Logs — compute counts, averages, and group-by operations over filtered log data.
• Logs URL for Explorer — generate a direct URL to the Logs Explorer with predefined filters and time range.
• Payload Model — request and response schema reference.