Sessions API
Real-time streaming scans with live results as each tool completes.
⚡ Watch Results Stream In Live
The Sessions API is our new streaming experience. Instead of waiting 2-5 minutes for all 150 modules to finish, you see each tool's results the moment it completes.
- • Start scan, wait 2-5 minutes
- • Get all results at once
- • No visibility into progress
- • Results appear immediately as tools finish
- • Real-time progress (23/150 modules done)
- • Automatic credit refunds for failed tools
🎯 Not a Developer? Start Here
Copy these prompts into Claude, ChatGPT, Cursor, or any AI assistant. Your AI will build what you need.
Quick Start Prompts
Common real-time scanning tasks you can accomplish with a single prompt.
📊 Build a Live Scan Dashboard
Watch results stream in real-time with a beautiful progress UI.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Build a live scan progress dashboard:
1. Start session: POST /api/sessions with target
2. Show session status and live progress bar
3. Poll /api/sessions/{sessionId}?progress=true every 2 seconds
4. Display: "23/150 tools complete (32%)"
5. As tools complete, add their results to a live list:
- Tool name, duration, issue count
- Color-code by severity (red=critical, orange=high, etc.)
6. When status is "completed", show final summary
7. If any tools failed, show refund credits received
Use smooth animations for new results appearing.
My stack: [YOUR_STACK]👩💻 Technical Details (for developers)
Polling Flow
// 1. Start session
const response = await fetch('/api/sessions', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
target: { url: 'https://myapp.com' },
categories: ['security', 'code-quality']
})
});
const { sessionId } = await response.json();
// 2. Poll for progress (lightweight)
const poll = async () => {
const res = await fetch(`/api/sessions/${sessionId}?progress=true`);
const { status, progress } = await res.json();
console.log(`${progress.completed}/${progress.total} (${progress.percentage}%)`);
if (status !== 'completed') {
setTimeout(poll, 2000);
}
};
poll();🔄 Get Only New Results (Efficient Polling)
Only fetch results that came in since your last poll - minimal bandwidth.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Build an efficient real-time results feed:
1. Start session: POST /api/sessions
2. Store the current timestamp
3. Every 2 seconds, call GET /api/sessions/{sessionId}?since={timestamp}
4. This returns ONLY tool reports added since that timestamp
5. Append new reports to your results list
6. Update timestamp to now for next poll
7. Stop polling when status is "completed"
This is much more efficient than fetching the full report each time.
My stack: [YOUR_STACK]👩💻 Technical Details (for developers)
Incremental Polling
let lastPoll = new Date().toISOString();
const allReports = [];
const pollForNewReports = async (sessionId) => {
const res = await fetch(
`/api/sessions/${sessionId}?since=${encodeURIComponent(lastPoll)}`
);
const { newReports, status } = await res.json();
// Add new reports to our list
allReports.push(...newReports);
lastPoll = new Date().toISOString();
// Show new reports
newReports.forEach(report => {
console.log(`✓ ${report.toolName}: ${report.findingsCount} findings`);
});
if (status !== 'completed') {
setTimeout(() => pollForNewReports(sessionId), 2000);
}
};🚀 CI/CD with Live Console Output
Show scan progress in your CI/CD logs as each tool completes.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions Create a CI/CD script with live console output: 1. Start session: POST /api/sessions 2. Print "[SCAN] Starting security scan..." 3. Poll every 5 seconds 4. As each tool completes, print: "[45/150] ✓ eslint-security: 3 findings (0.8s)" "[45/150] ✓ semgrep: 1 critical, 2 high (2.3s)" 5. If a tool fails, print warning but continue 6. When done, print summary table: - Total findings by severity - Credits refunded for failed tools 7. Exit code 1 if critical > 0 or high > 5 Use ANSI colors for pretty console output. My stack: [YOUR_STACK]
⚛️ React Hook for Live Sessions
A custom React hook that manages the whole polling lifecycle.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Create a useSessionPolling React hook:
const { session, progress, isComplete, error, startSession } = useSessionPolling();
Features:
1. startSession(target) - starts a new session
2. Automatically polls for progress every 2 seconds
3. Stops polling when complete
4. Returns:
- session: full session data
- progress: { completed, total, percentage }
- isComplete: boolean
- error: any error that occurred
5. Cleanup: stops polling when component unmounts
Use React Query or SWR for caching.
My stack: React with TypeScript👩💻 Technical Details (for developers)
Example Implementation
import { useState, useEffect, useCallback } from 'react';
export function useSessionPolling(options = {}) {
const { pollInterval = 2000, autoStart = false } = options;
const [sessionId, setSessionId] = useState(null);
const [session, setSession] = useState(null);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
const startSession = useCallback(async (target) => {
setIsLoading(true);
try {
const res = await fetch('/api/sessions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ target })
});
const data = await res.json();
setSessionId(data.sessionId);
} catch (err) {
setError(err);
}
}, []);
useEffect(() => {
if (!sessionId) return;
const poll = async () => {
const res = await fetch(`/api/sessions/${sessionId}`);
const data = await res.json();
setSession(data);
setIsLoading(false);
if (data.status !== 'completed') {
setTimeout(poll, pollInterval);
}
};
poll();
}, [sessionId, pollInterval]);
return {
session,
progress: session?.progress,
isComplete: session?.status === 'completed',
isLoading,
error,
startSession
};
}Start a Session
Start a Streaming Audit
Begin a new scan session. Results stream in as each tool completes.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Add a streaming scan to my app:
1. POST to /api/sessions with:
- target: { url: "https://myapp.com" } or { directory: "/path/to/code" }
- categories: ['security', 'code-quality'] (optional)
- enableIntelligence: true (for AI-powered analysis)
2. Returns sessionId immediately
3. Poll /api/sessions/{sessionId} for live results
4. Show results as they come in
Handle 402 error for insufficient credits.
My stack: [YOUR_STACK]👩💻 Technical Reference
/api/sessionsStart a new streaming audit session. Returns immediately with session ID and polling URLs.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
target | object | Yes | What to scan (see below) |
target.url | string | * | Live URL to scan |
target.urls | string[] | * | Multiple URLs to scan |
target.directory | string | * | Local directory path |
categories | string[] | No | security, code-quality, accessibility, performance |
tools | string[] | No | Specific tools to run (overrides categories) |
excludeTools | string[] | No | Tools to skip |
enableIntelligence | boolean | No | Generate AI analysis (default: true) |
timeout | number | No | Max ms per tool (default: 300000) |
maxConcurrent | number | No | Parallel tools (default: 5) |
* One of url, urls, or directory is required
Example Request
curl -X POST https://bugrit.com/api/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": {
"url": "https://myapp.com"
},
"categories": ["security", "code-quality"],
"enableIntelligence": true
}'Response (202 Accepted)
{
"sessionId": "sess-abc123xyz",
"scanId": "scan-1705834200-a1b2c3",
"status": "started",
"message": "Audit session started. Poll /api/sessions/{sessionId} for real-time updates.",
"pollUrls": {
"full": "/api/sessions/sess-abc123xyz",
"progress": "/api/sessions/sess-abc123xyz?progress=true",
"newReports": "/api/sessions/sess-abc123xyz?since={timestamp}"
}
}Poll Session
Get Real-Time Results
Poll for live updates. Three modes: full report, progress only, or incremental.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Build a polling system with three modes:
1. Progress only (lightweight):
GET /api/sessions/{id}?progress=true
→ Returns just { status, progress: { completed, total, percentage } }
→ Use for progress bars, minimal bandwidth
2. Incremental updates:
GET /api/sessions/{id}?since={ISO_timestamp}
→ Returns only NEW tool reports since that time
→ Most efficient for live feeds
3. Full report:
GET /api/sessions/{id}
→ Returns everything including all tool reports
→ Use when you need the complete picture
Start with progress-only, switch to incremental for results.
My stack: [YOUR_STACK]👩💻 Technical Details (for developers)
/api/sessions/:sessionIdQuery Parameters
| Parameter | Type | Description |
|---|---|---|
progress | boolean | If true, returns only status and progress counts |
since | ISO timestamp | Returns only reports added after this time |
Full Response
{
"sessionId": "sess-abc123xyz",
"userId": "user-123",
"status": "running",
"progress": {
"total": 150,
"completed": 23,
"failed": 1,
"skipped": 2,
"running": 5,
"pending": 40,
"percentage": 32
},
"toolReports": {
"eslint-security": {
"toolName": "eslint-security",
"category": "security",
"status": "completed",
"duration": 1234,
"findingsCount": 3,
"result": { ... },
"completedAt": "2026-01-22T10:30:15Z"
},
"semgrep": {
"toolName": "semgrep",
"category": "security",
"status": "completed",
"duration": 2567,
"findingsCount": 5,
"result": { ... },
"completedAt": "2026-01-22T10:30:18Z"
}
},
"summary": {
"totalFindings": 8,
"bySeverity": {
"critical": 1,
"high": 2,
"medium": 3,
"low": 2
},
"byCategory": {
"security": 5,
"code-quality": 3
},
"toolsRun": 23,
"toolsSkipped": 2,
"toolsFailed": 1
},
"lastUpdated": "2026-01-22T10:30:18Z"
}Progress-Only Response
{
"sessionId": "sess-abc123xyz",
"status": "running",
"progress": {
"total": 150,
"completed": 23,
"failed": 1,
"skipped": 2,
"running": 5,
"pending": 40,
"percentage": 32
},
"lastUpdated": "2026-01-22T10:30:18Z"
}Incremental Response
{
"sessionId": "sess-abc123xyz",
"status": "running",
"progress": { ... },
"newReports": [
{
"toolName": "trivy",
"category": "security",
"status": "completed",
"duration": 1890,
"findingsCount": 2,
"result": { ... },
"completedAt": "2026-01-22T10:30:20Z"
}
],
"lastUpdated": "2026-01-22T10:30:20Z"
}List Sessions
View Session History
Get a list of your recent scan sessions.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions Create a session history component: 1. Fetch GET /api/sessions?limit=20 2. Display as table: - Created date - Status badge (running=blue, completed=green, failed=red) - Progress (45/150 tools) - Issue summary (2 critical, 5 high) 3. Click row to view full session 4. Running sessions: show progress bar + live badge My stack: [YOUR_STACK]
👩💻 Technical Details (for developers)
/api/sessionsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Max results (default: 20) |
Response
{
"sessions": [
{
"sessionId": "sess-abc123xyz",
"status": "completed",
"progress": { "total": 150, "completed": 150, "percentage": 100 },
"createdAt": "2026-01-22T10:25:00Z",
"completedAt": "2026-01-22T10:30:47Z"
}
],
"total": 1
}Automatic Credit Refunds
💰 You Only Pay for Results
If a tool fails, times out, or gets skipped, you automatically get those credits back. Check the refund field in your completed session.
// In your completed session response:
{
"status": "completed",
"refund": {
"refundedCredits": 150,
"toolsRefunded": ["tool-that-failed", "tool-that-timed-out"],
"newBalance": 4850
}
}Session Status Values
| Status | Description |
|---|---|
initializing | Session created, modules being prepared |
running | Modules actively running, results streaming in |
completed | All modules finished successfully |
partial | Completed with some modules failed/skipped |
failed | Session failed (check error field) |
Tool Report Status Values
| Status | Description |
|---|---|
pending | Tool queued, waiting to run |
running | Tool currently executing |
completed | Tool finished with results |
failed | Tool encountered an error (credits refunded) |
skipped | Tool skipped (circuit breaker open, etc.) |
Migrating from Scans API
Upgrade Your Integration
Switch from the old Scans API to the new Sessions API.
Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions
Migrate my existing scan integration to use Sessions:
Old code uses:
- POST /api/v1/scans to start
- GET /api/v1/scans/{id} to poll
Change to:
- POST /api/sessions to start (note: different request body)
- GET /api/sessions/{id}?progress=true for quick polls
- GET /api/sessions/{id}?since={timestamp} for incremental results
Key differences:
1. Request body uses "target" object instead of flat fields
2. Response has "sessionId" not "scanId"
3. Real-time progress available immediately
4. Automatic credit refunds for failures
Keep backward compatibility if needed.
My stack: [YOUR_STACK]