GET /api/logs

Retrieve error logs with filtering and pagination

GET https://vij.example.com/api/logs

GET /api/logs

cURL

curl --request GET \
  --url https://vij.example.com/api/logs

Success (200)

{
  "logs": [
    {
      "_id": "65a1b2c3d4e5f6g7h8i9j0k1",
      "message": "Payment processing failed",
      "name": "Error",
      "stack": "Error: Payment processing failed\n    at processPayment (payment.js:45:12)\n    at handleCheckout (checkout.js:123:5)",
      "severity": "error",
      "timestamp": "2024-01-01T12:34:56.789Z",
      "appId": "my-frontend-app",
      "environment": "production",
      "metadata": {
        "userId": "user-123",
        "orderId": "order-456",
        "feature": "checkout"
      },
      "context": {
        "viewport": { "width": 1920, "height": 1080 },
        "browser": {
          "userAgent": "Mozilla/5.0...",
          "language": "en-US"
        }
      },
      "group": "abc123def456",
      "aiAnalysis": {
        "summary": "Payment object was undefined when processing transaction",
        "possibleCause": "API request failed or user session expired",
        "suggestedFix": "Add null check before accessing payment.amount"
      }
    },
    {
      "_id": "65a1b2c3d4e5f6g7h8i9j0k2",
      "message": "Database connection timeout",
      "name": "TimeoutError",
      "stack": "TimeoutError: Connection timeout\n    at connect (db.js:23:10)",
      "severity": "error",
      "timestamp": "2024-01-01T12:30:00.000Z",
      "appId": "backend-api",
      "environment": "production",
      "metadata": {
        "database": "mongodb",
        "timeout": 5000
      },
      "context": {
        "process": {
          "pid": 12345,
          "platform": "linux",
          "nodeVersion": "v20.0.0"
        }
      },
      "group": "def456ghi789"
    }
  ],
  "total": 1547,
  "page": 1,
  "limit": 50,
  "pages": 31
}

The GET /api/logs endpoint retrieves stored error logs with support for filtering, searching, sorting, and pagination.

Query Parameters

severity · string

Filter by severity level.

Values: error, warning, info

Example: /api/logs?severity=error

environment · string

Filter by environment name.

Example: /api/logs?environment=production

appId · string

Filter by application ID.

Example: /api/logs?appId=my-frontend-app

search · string

Full-text search across message and stack fields.

Example: /api/logs?search=TypeError

startDate · string

Filter logs created after this date (ISO 8601).

Example: /api/logs?startDate=2024-01-01T00:00:00Z

endDate · string

Filter logs created before this date (ISO 8601).

Example: /api/logs?endDate=2024-01-31T23:59:59Z

page · number · default: "1"

Page number for pagination (1-indexed).

Example: /api/logs?page=2

limit · number · default: "50"

Number of results per page (max: 100).

Example: /api/logs?limit=100

sortBy · string · default: "timestamp"

Field to sort by.

Values: timestamp, severity, appId, environment

Example: /api/logs?sortBy=severity

sortOrder · string · default: "desc"

Sort order.

Values: asc (ascending), desc (descending)

Example: /api/logs?sortOrder=asc

group · string

Filter by error group fingerprint.

Example: /api/logs?group=abc123def456

Response Fields

logs · array

Array of error log objects.

Show Log object properties

_id · string

MongoDB ObjectId of the log entry.

message · string

Error message.

name · string

Error name/type.

stack · string

Stack trace.

severity · string

Severity level: error, warning, or info.

timestamp · string

ISO 8601 timestamp when error occurred.

appId · string

Application identifier.

environment · string

Environment name.

metadata · object

Custom metadata attached to the error.

context · object

Browser or Node.js context information.

group · string

Error group fingerprint for deduplication.

aiAnalysis · object

AI-generated analysis (if available).

Show AI analysis properties

summary · string

Concise error summary.

possibleCause · string

Root cause analysis.

suggestedFix · string

Recommended fix suggestions.

total · number

Total number of logs matching the query.

page · number

Current page number.

limit · number

Results per page.

pages · number

Total number of pages.

Example Requests

Get All Errors

curl "https://vij.example.com/api/logs?severity=error"

Example Response

Success (200)

{
  "logs": [
    {
      "_id": "65a1b2c3d4e5f6g7h8i9j0k1",
      "message": "Payment processing failed",
      "name": "Error",
      "stack": "Error: Payment processing failed\n    at processPayment (payment.js:45:12)\n    at handleCheckout (checkout.js:123:5)",
      "severity": "error",
      "timestamp": "2024-01-01T12:34:56.789Z",
      "appId": "my-frontend-app",
      "environment": "production",
      "metadata": {
        "userId": "user-123",
        "orderId": "order-456",
        "feature": "checkout"
      },
      "context": {
        "viewport": { "width": 1920, "height": 1080 },
        "browser": {
          "userAgent": "Mozilla/5.0...",
          "language": "en-US"
        }
      },
      "group": "abc123def456",
      "aiAnalysis": {
        "summary": "Payment object was undefined when processing transaction",
        "possibleCause": "API request failed or user session expired",
        "suggestedFix": "Add null check before accessing payment.amount"
      }
    },
    {
      "_id": "65a1b2c3d4e5f6g7h8i9j0k2",
      "message": "Database connection timeout",
      "name": "TimeoutError",
      "stack": "TimeoutError: Connection timeout\n    at connect (db.js:23:10)",
      "severity": "error",
      "timestamp": "2024-01-01T12:30:00.000Z",
      "appId": "backend-api",
      "environment": "production",
      "metadata": {
        "database": "mongodb",
        "timeout": 5000
      },
      "context": {
        "process": {
          "pid": 12345,
          "platform": "linux",
          "nodeVersion": "v20.0.0"
        }
      },
      "group": "def456ghi789"
    }
  ],
  "total": 1547,
  "page": 1,
  "limit": 50,
  "pages": 31
}

Error Responses

Bad Request (400)

{
  "error": "Invalid severity value. Must be 'error', 'warning', or 'info'"
}

Filtering Examples

By Severity

# Get only errors
GET /api/logs?severity=error

# Get warnings and info
GET /api/logs?severity=warning
GET /api/logs?severity=info

By Environment

# Production errors only
GET /api/logs?environment=production&severity=error

# Staging errors
GET /api/logs?environment=staging&severity=error

By Application

# Specific app
GET /api/logs?appId=my-frontend-app

# Multiple apps (requires multiple queries or custom implementation)
GET /api/logs?appId=my-frontend-app
GET /api/logs?appId=my-backend-app

By Date Range

# Last 24 hours
GET /api/logs?startDate=$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)

# Specific month
GET /api/logs?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

# Today's errors
GET /api/logs?startDate=$(date -u +%Y-%m-%dT00:00:00Z)

Full-Text Search

# Search for specific error
GET /api/logs?search=TypeError

# Search in specific app
GET /api/logs?search=payment&appId=my-app

# Search with phrase
GET /api/logs?search="cannot%20read%20property"

Combined Filters

# Complex query
GET /api/logs?severity=error&environment=production&appId=my-app&search=payment&startDate=2024-01-01T00:00:00Z&limit=25

Pagination

Navigate through large result sets:

# First page
GET /api/logs?page=1&limit=50

# Second page
GET /api/logs?page=2&limit=50

# Large page size
GET /api/logs?page=1&limit=100  # Max: 100

Response includes:

• total - Total matching logs
• page - Current page
• limit - Items per page
• pages - Total pages

Calculate next page:

if (page < pages) {
  const nextPage = page + 1;
  fetch(`/api/logs?page=${nextPage}&limit=${limit}`);
}

Sorting

Sort results by different fields:

# Newest first (default)
GET /api/logs?sortBy=timestamp&sortOrder=desc

# Oldest first
GET /api/logs?sortBy=timestamp&sortOrder=asc

# Sort by severity
GET /api/logs?sortBy=severity&sortOrder=desc

# Sort by app
GET /api/logs?sortBy=appId&sortOrder=asc

Performance Considerations

Use time filters

Always include time filters to reduce query scope:

# Good - scans less data
GET /api/logs?startDate=2024-01-01T00:00:00Z

# Slow - scans all data
GET /api/logs

Limit page size

Use reasonable page sizes:

# Good
GET /api/logs?limit=50

# Slow
GET /api/logs?limit=10000

Maximum allowed: 100 items per page

Use indexed fields

These fields are indexed for fast queries:

• timestamp
• severity
• environment
• appId
• group

Metadata fields are not indexed by default.

Text search performance

Full-text search uses MongoDB text index:

# Fast (indexed)
GET /api/logs?search=TypeError

# Slower on large datasets
GET /api/logs?search=very%20specific%20long%20phrase

Client Implementation

JavaScript/TypeScript

interface LogQuery {
  severity?: 'error' | 'warning' | 'info';
  environment?: string;
  appId?: string;
  search?: string;
  startDate?: string;
  endDate?: string;
  page?: number;
  limit?: number;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
}

async function fetchLogs(query: LogQuery) {
  const params = new URLSearchParams(
    Object.entries(query)
      .filter(([_, v]) => v !== undefined)
      .map(([k, v]) => [k, String(v)])
  );

  const response = await fetch(
    `https://vij.example.com/api/logs?${params}`
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

// Usage
const logs = await fetchLogs({
  severity: 'error',
  environment: 'production',
  page: 1,
  limit: 50
});

Python

import requests
from typing import Optional, Literal

def fetch_logs(
    severity: Optional[Literal['error', 'warning', 'info']] = None,
    environment: Optional[str] = None,
    app_id: Optional[str] = None,
    search: Optional[str] = None,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    page: int = 1,
    limit: int = 50
):
    params = {
        k: v for k, v in {
            'severity': severity,
            'environment': environment,
            'appId': app_id,
            'search': search,
            'startDate': start_date,
            'endDate': end_date,
            'page': page,
            'limit': limit
        }.items() if v is not None
    }

    response = requests.get(
        'https://vij.example.com/api/logs',
        params=params
    )

    response.raise_for_status()
    return response.json()

# Usage
logs = fetch_logs(
    severity='error',
    environment='production',
    page=1,
    limit=50
)

Rate Limiting

No rate limiting by default. Implement rate limiting in production.

Recommended limits:

• 100 requests per minute per IP
• 1,000 requests per hour per user

Caching

Responses can be cached for performance:

# Cache-Control header
Cache-Control: public, max-age=60

Cache key should include:

• All query parameters
• Current time bucket (e.g., minute)

Related Endpoints

POST /api/logs

Send error logs to VIJ

GET /api/stats

Get error statistics

GET /api/groups

Retrieve error groups

Filtering Guide

Advanced filtering techniques