GET /api/groups

The GET /api/groups endpoint retrieves deduplicated error groups, showing unique errors with their occurrence counts and metadata.

Query Parameters

environment

string

Filter groups by environment.Example: /api/groups?environment=production

appId

string

Filter groups by application ID.Example: /api/groups?appId=my-frontend-app

severity

string

Filter by highest severity in the group.Values: error, warning, infoExample: /api/groups?severity=error

startDate

string

Filter groups with occurrences after this date (ISO 8601).Example: /api/groups?startDate=2024-01-01T00:00:00Z

endDate

string

Filter groups with occurrences before this date (ISO 8601).Example: /api/groups?endDate=2024-01-31T23:59:59Z

minCount

number

Filter groups with at least this many occurrences.Example: /api/groups?minCount=10

page

number

default:"1"

Page number for pagination (1-indexed).Example: /api/groups?page=2

limit

number

default:"50"

Number of results per page (max: 100).Example: /api/groups?limit=100

sortBy

string

default:"count"

Field to sort by.Values: count, lastSeen, firstSeen, severityExample: /api/groups?sortBy=lastSeen

sortOrder

string

default:"desc"

Sort order.Values: asc (ascending), desc (descending)Example: /api/groups?sortOrder=asc

Response Fields

groups

array

Array of error group objects.

Show Group object properties

group

string

Unique fingerprint hash identifying this error group.

message

string

Representative error message from the group.

name

string

Error name/type (e.g., TypeError, ReferenceError).

stack

string

Representative stack trace from the group.

count

number

Total number of occurrences in this group.

severity

string

Highest severity level in the group: error, warning, or info.

firstSeen

string

ISO 8601 timestamp of the first occurrence.

lastSeen

string

ISO 8601 timestamp of the most recent occurrence.

affectedApps

array

List of application IDs where this error occurred.

["frontend", "mobile-app"]

affectedEnvironments

array

List of environments where this error occurred.

["production", "staging"]

affectedUsers

number

Number of unique users affected (if userId in metadata).

recentOccurrences

array

Sample of recent log IDs from this group (last 5).

["65a1b2c3d4e5f6g7h8i9j0k1", "65a1b2c3d4e5f6g7h8i9j0k2"]

total

number

Total number of groups matching the query.

page

number

Current page number.

limit

number

Results per page.

pages

number

Total number of pages.

Example Requests

curl "https://vij.example.com/api/groups"

Example Response

{
  "groups": [
    {
      "group": "abc123def456",
      "message": "TypeError: Cannot read property 'map' of undefined",
      "name": "TypeError",
      "stack": "TypeError: Cannot read property 'map' of undefined\n    at processData (app.js:123:45)\n    at renderList (components/List.tsx:67:12)",
      "count": 2547,
      "severity": "error",
      "firstSeen": "2024-01-01T10:00:00Z",
      "lastSeen": "2024-01-03T14:30:00Z",
      "affectedApps": ["frontend", "mobile-app"],
      "affectedEnvironments": ["production"],
      "affectedUsers": 456,
      "recentOccurrences": [
        "65a1b2c3d4e5f6g7h8i9j0k1",
        "65a1b2c3d4e5f6g7h8i9j0k2",
        "65a1b2c3d4e5f6g7h8i9j0k3"
      ]
    },
    {
      "group": "def456ghi789",
      "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)",
      "count": 1234,
      "severity": "error",
      "firstSeen": "2024-01-02T08:00:00Z",
      "lastSeen": "2024-01-03T15:00:00Z",
      "affectedApps": ["frontend"],
      "affectedEnvironments": ["production", "staging"],
      "affectedUsers": 234,
      "recentOccurrences": [
        "65a1b2c3d4e5f6g7h8i9j0k4",
        "65a1b2c3d4e5f6g7h8i9j0k5"
      ]
    }
  ],
  "total": 347,
  "page": 1,
  "limit": 50,
  "pages": 7
}

Use Cases

Dashboard Overview

Display top error groups:

const { groups } = await fetch(
  'https://vij.example.com/api/groups?sortBy=count&sortOrder=desc&limit=10'
).then(r => r.json());

groups.forEach(group => {
  console.log(`${group.message}: ${group.count} occurrences`);
});

Identify New Issues

Find groups that appeared recently:

const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();

const { groups } = await fetch(
  `https://vij.example.com/api/groups?startDate=${yesterday}&sortBy=firstSeen&sortOrder=desc`
).then(r => r.json());

// New error groups in last 24 hours
console.log(`${groups.length} new error groups detected`);

High-Impact Errors

Find errors affecting many users:

const { groups } = await fetch(
  'https://vij.example.com/api/groups?minCount=100&sortBy=count&sortOrder=desc'
).then(r => r.json());

// High-frequency errors
groups.forEach(group => {
  console.log(`${group.message}: ${group.affectedUsers} users affected`);
});

Application Health

Compare error groups across apps:

const frontendGroups = await fetch(
  'https://vij.example.com/api/groups?appId=frontend'
).then(r => r.json());

const backendGroups = await fetch(
  'https://vij.example.com/api/groups?appId=backend-api'
).then(r => r.json());

console.log(`Frontend: ${frontendGroups.total} unique errors`);
console.log(`Backend: ${backendGroups.total} unique errors`);

Filtering Examples

By Frequency

# High-frequency errors (100+ occurrences)
GET /api/groups?minCount=100

# Low-frequency errors (1-10 occurrences)
GET /api/groups?minCount=1&maxCount=10

By Time

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

# Groups first seen this week
startDate=$(date -u -d 'last monday' +%Y-%m-%dT00:00:00Z)
GET /api/groups?startDate=$startDate&sortBy=firstSeen

By Severity

# Critical errors only
GET /api/groups?severity=error

# All severities in production
GET /api/groups?environment=production

Combined Filters

# High-frequency production errors
GET /api/groups?environment=production&severity=error&minCount=50&sortBy=count&sortOrder=desc

# Recent low-frequency warnings
GET /api/groups?severity=warning&minCount=1&maxCount=10&sortBy=lastSeen&sortOrder=desc

Sorting Options

By Count (Most Frequent)

GET /api/groups?sortBy=count&sortOrder=desc

Use Case: Find the most impactful errors to fix first.

By Last Seen (Most Recent)

GET /api/groups?sortBy=lastSeen&sortOrder=desc

Use Case: Monitor active issues and recent deployments.

By First Seen (Newest Issues)

GET /api/groups?sortBy=firstSeen&sortOrder=desc

Use Case: Identify new bugs introduced recently.

By Severity

GET /api/groups?sortBy=severity&sortOrder=desc

Use Case: Prioritize critical errors over warnings.

Getting Group Details

To get all occurrences of a specific group:

# Get group fingerprint from /api/groups
group="abc123def456"

# Fetch all occurrences
curl "https://vij.example.com/api/logs?group=$group"

Response: All individual error logs in that group.

Pagination

Navigate through large result sets:

async function getAllGroups() {
  let page = 1;
  let allGroups = [];
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://vij.example.com/api/groups?page=${page}&limit=100`
    ).then(r => r.json());

    allGroups = allGroups.concat(response.groups);

    hasMore = page < response.pages;
    page++;
  }

  return allGroups;
}

Performance Optimization

Use time filters

# Good - last 30 days
startDate=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ)
GET /api/groups?startDate=$startDate

# Slow - all time
GET /api/groups

Filter by app or environment

# Faster - single app
GET /api/groups?appId=my-app

# Slower - all apps
GET /api/groups

Use minCount to reduce results

# Faster - high-frequency only
GET /api/groups?minCount=50

# Slower - includes one-off errors
GET /api/groups

Limit page size appropriately

# Good for most cases
GET /api/groups?limit=50

# Use larger for batch processing
GET /api/groups?limit=100

Client Implementation

TypeScript

interface GroupsQuery {
  environment?: string;
  appId?: string;
  severity?: 'error' | 'warning' | 'info';
  startDate?: string;
  endDate?: string;
  minCount?: number;
  page?: number;
  limit?: number;
  sortBy?: 'count' | 'lastSeen' | 'firstSeen' | 'severity';
  sortOrder?: 'asc' | 'desc';
}

interface ErrorGroup {
  group: string;
  message: string;
  name: string;
  stack: string;
  count: number;
  severity: string;
  firstSeen: string;
  lastSeen: string;
  affectedApps: string[];
  affectedEnvironments: string[];
  affectedUsers: number;
  recentOccurrences: string[];
}

interface GroupsResponse {
  groups: ErrorGroup[];
  total: number;
  page: number;
  limit: number;
  pages: number;
}

async function fetchGroups(query: GroupsQuery = {}): Promise<GroupsResponse> {
  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/groups?${params}`
  );

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

  return response.json();
}

// Usage
const groups = await fetchGroups({
  environment: 'production',
  severity: 'error',
  minCount: 10,
  sortBy: 'count',
  sortOrder: 'desc',
  limit: 20
});

React Hook

import { useState, useEffect } from 'react';

function useErrorGroups(query: GroupsQuery) {
  const [groups, setGroups] = useState<ErrorGroup[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    async function load() {
      try {
        setLoading(true);
        const data = await fetchGroups(query);
        setGroups(data.groups);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    }

    load();
  }, [JSON.stringify(query)]);

  return { groups, loading, error };
}

// Usage in component
function ErrorGroupsList() {
  const { groups, loading, error } = useErrorGroups({
    environment: 'production',
    severity: 'error',
    minCount: 10
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {groups.map(group => (
        <li key={group.group}>
          {group.message} ({group.count} occurrences)
        </li>
      ))}
    </ul>
  );
}

Exporting Group Data

Export groups for reporting:

# Export as JSON
curl "https://vij.example.com/api/groups?environment=production" > groups.json

# Export as CSV (requires custom endpoint or processing)
curl "https://vij.example.com/api/groups/export?format=csv&environment=production" > groups.csv

Monitoring Trends

Track how groups change over time:

// Daily group count tracking
async function trackGroupTrends() {
  const today = await fetch('/api/groups').then(r => r.json());
  const yesterday = await fetch(
    `/api/groups?endDate=${new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()}`
  ).then(r => r.json());

  const change = today.total - yesterday.total;
  console.log(`Group change: ${change > 0 ? '+' : ''}${change}`);

  if (change > 10) {
    alert(`Warning: ${change} new error groups detected!`);
  }
}

GET /api/logs

Get individual error logs by group

GET /api/stats

Get statistics including group counts

Error Grouping

Learn how error grouping works

Dashboard Features

View groups in the dashboard

Ingestion API

Analytics API

GET /api/groups

Query Parameters

Response Fields

Example Requests

Example Response

Use Cases

Dashboard Overview

Identify New Issues

High-Impact Errors

Application Health

Filtering Examples

By Frequency

By Time

By Severity

Combined Filters

Sorting Options

By Count (Most Frequent)

By Last Seen (Most Recent)

By First Seen (Newest Issues)

By Severity

Getting Group Details

Performance Optimization

Client Implementation

TypeScript

React Hook

Exporting Group Data

Monitoring Trends

GET /api/logs

GET /api/stats

Error Grouping

Dashboard Features

Ingestion API

Analytics API

​Query Parameters

​Response Fields

​Example Requests

​Example Response

​Use Cases

​Dashboard Overview

​Identify New Issues

​High-Impact Errors

​Application Health

​Filtering Examples

​By Frequency

​By Time

​By Severity

​Combined Filters

​Sorting Options

​By Count (Most Frequent)

​By Last Seen (Most Recent)

​By First Seen (Newest Issues)

​By Severity

​Getting Group Details

​Pagination

​Performance Optimization

​Client Implementation

​TypeScript

​React Hook

​Exporting Group Data

​Monitoring Trends

​Related Endpoints

GET /api/logs

GET /api/stats

Error Grouping

Dashboard Features

Query Parameters

Response Fields

Example Requests

Example Response

Use Cases

Dashboard Overview

Identify New Issues

High-Impact Errors

Application Health

Filtering Examples

By Frequency

By Time

By Severity

Combined Filters

Sorting Options

By Count (Most Frequent)

By Last Seen (Most Recent)

By First Seen (Newest Issues)

By Severity

Getting Group Details

Pagination

Performance Optimization

Client Implementation

TypeScript

React Hook

Exporting Group Data

Monitoring Trends

Related Endpoints