Analytics

Analytics and Reporting

Access detailed analytics about your security scanning activity, threat detection trends, and usage patterns.

Daily Scan Activity

`GET /api/analytics/scans/daily`

Retrieves daily scan counts for the past 30 days, including summary statistics.

Example

curl -sS \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/analytics/scans/daily'

Response (200)

{
  "success": true,
  "data": {
    "daily": [
      {
        "date": "1-15",
        "fullDate": "2026-01-15",
        "value": 24
      },
      {
        "date": "1-16",
        "fullDate": "2026-01-16",
        "value": 18
      },
      {
        "date": "2-14",
        "fullDate": "2026-02-14",
        "value": 32
      }
    ],
    "summary": {
      "totalScans": 567,
      "avgPerDay": 18.9,
      "maxInDay": 45,
      "period": "30 days"
    }
  }
}

Response Fields

Field	Type	Description
`daily`	array	Array of daily scan counts for the past 30 days
`daily[].date`	string	Display date in M-D format (e.g., "2-14")
`daily[].fullDate`	string	Full date in YYYY-MM-DD format
`daily[].value`	number	Number of scans performed on that day
`summary.totalScans`	number	Total scans in the 30-day period
`summary.avgPerDay`	number	Average scans per day (rounded to 1 decimal)
`summary.maxInDay`	number	Maximum scans in a single day
`summary.period`	string	Time period covered ("30 days")

Use Cases

Plot scan volume trends over time
Identify peak usage days
Monitor scanning patterns for capacity planning
Generate usage reports for stakeholders

Scan Summary Statistics

`GET /api/analytics/scans/summary`

Retrieves aggregate statistics about your security scans.

Example

curl -sS \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/analytics/scans/summary'

Response (200)

{
  "success": true,
  "data": {
    "totalScans": 1247,
    "threatScans": 89,
    "recentScans": 156
  }
}

Response Fields

Field	Type	Description
`totalScans`	number	Total number of scans performed (all time)
`threatScans`	number	Number of scans that detected threats
`recentScans`	number	Number of scans in the last 30 days

Calculated Metrics

You can derive additional metrics from the response:

Threat Detection Rate: (threatScans / totalScans) * 100
Recent Activity Rate: (recentScans / totalScans) * 100
Clean Scans: totalScans - threatScans

Example Calculations

const { totalScans, threatScans, recentScans } = response.data;

// Calculate threat detection percentage
const threatRate = ((threatScans / totalScans) * 100).toFixed(2);
console.log(`Threat Detection Rate: ${threatRate}%`);

// Calculate clean scan count
const cleanScans = totalScans - threatScans;
console.log(`Clean Scans: ${cleanScans}`);

// Calculate recent activity percentage
const recentActivityRate = ((recentScans / totalScans) * 100).toFixed(2);
console.log(`Recent Activity: ${recentActivityRate}%`);

Integration Examples

Display key metrics in a dashboard:

async function fetchAnalyticsSummary() {
  const response = await fetch('https://api.sieve.godel-labs.ai/api/analytics/scans/summary', {
    headers: {
      'X-API-Key': process.env.API_KEY
    }
  });
  
  const { data } = await response.json();
  
  return {
    total: data.totalScans,
    threats: data.threatScans,
    clean: data.totalScans - data.threatScans,
    recent: data.recentScans,
    threatRate: ((data.threatScans / data.totalScans) * 100).toFixed(1) + '%'
  };
}

Time-Series Chart

Fetch daily data for visualization:

async function fetchDailyTrends() {
  const response = await fetch('https://api.sieve.godel-labs.ai/api/analytics/scans/daily', {
    headers: {
      'X-API-Key': process.env.API_KEY
    }
  });
  
  const { data } = await response.json();
  
  // Format for charting library (e.g., Chart.js)
  return {
    labels: data.daily.map(d => d.date),
    values: data.daily.map(d => d.value),
    summary: data.summary
  };
}

Notes

Scoped to your account: Analytics reflect the scans associated with your API key
Historical Data: Daily analytics cover the past 30 days with missing days filled as zero
Real-time Updates: Summary statistics reflect the current state and update immediately after new scans
Date Format: Daily data uses M-D format for display, but includes fullDate (YYYY-MM-DD) for accurate parsing
Time Zone: All dates are in UTC