Logo
Docs

Search Logs

Learn how to search logs via the API.

Endpoint

The endpoint to search logs is:

https://api.vigilant.run/api/v1/logs/search

Authentication

To authenticate with Vigilant's API, you need to provide an API key in the header of your request. You can create an API key in the Vigilant dashboard.

X-API-KEY: tk_0123456789

Example

Here's an example of how to search logs:

curl -X POST "https://api.vigilant.run/api/v1/logs/search" \
  -H "X-API-KEY: tk_0123456789" \
  -H "Content-Type: application/json" \
  -d '{"filters": [{"field": "level", "operator": "equals", "value": "error"}]}'

Request

The request body is a JSON object. The fields are used to filter the logs. All fields are optional.

{
  // Search for logs with this term, case insensitive
  // Must be a string value
  "search_term": "received an error",

  // Return logs after this timestamp
  // Must be an ISO timestamp
  "start_timestamp": "2025-05-16T00:00:00Z",

  // Return logs before this timestamp
  // Must be an ISO timestamp
  "end_timestamp": "2025-05-16T00:00:00Z",

  // Return at most this many logs
  "limit": 100,

  // Filter logs by these attributes
  "filters": [
    {
      // Field to filter by
      // Options are 'level', 'body', or any user-defined attributes
      "field": "user_email",

      // Filter by operator
      // Options are 'equals', 'not_equals', 'contains', 'not_contains', 'exists', 'not_exists'
      "operator": "equals",

      // Value to filter by
      // Must be a string, not required if operator is 'exists' or 'not_exists'
      "value": "test@test.com",
    },
  ],

  // Cursor to start from, returns only logs after this cursor
  "cursor_start": {
    "log_id": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-05-16T00:00:00Z"
  },

  // Order by timestamp
  // Options are asc, desc
  "order_by": "desc"
}

Response

The response is a JSON object.

{
  // Array of logs
  "logs": [
    {
      // Unique identifier for the log, used for pagination
      "log_id": "00000000-0000-0000-0000-000000000000",

      // Timestamp of the log
      "timestamp": "2025-05-16T00:00:00Z",

      // Level of the log
      // Options are debug, info, warn, error, and trace
      "level": "error",

      // Body of the log
      "body": "This is an error log",

      // Custom attributes of the log
      "attributes": {
        "user_email": "test@test.com",
        "error_code": "123456"
      }
    }
  ]
}

Pagination

To get the next page of logs, set the cursor_start field to the log_id and timestamp of the last log in the current page and keep all the other fields the same. That will return the next page of logs.

{
  "cursor_start": {
    "log_id": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-05-16T00:00:00Z"
  }
}