> ## Documentation Index > Fetch the complete documentation index at: https://docs.socdefenders.ai/llms.txt > Use this file to discover all available pages before exploring further. # Aggregated IOC statistics and trends > Pre-computed aggregations over the entire IOC corpus. Backed by the `iocs_stats_cache` table (refreshed every 10 minutes via pg_cron) — sub-millisecond response time. ## What you get - Total IOC count and total article count - Breakdown by IOC type (ipv4, domain, hash, etc.) - Breakdown by source feed - Breakdown by category (news, research, threat-intel, vendor, government) - Last 24h and last 7d trend - Feed health (healthy / degraded / error) - Top MITRE ATT&CK techniques - Top CVEs ## Use cases - **Dashboard tiles**: "23,541 indicators ingested in the last 24h" - **Trend charts**: 7-day rolling counts for sparklines - **Coverage analysis**: which sources contribute most volume - **Health monitoring**: detect when a feed stops producing IOCs ## Cache headers Response includes: - `X-Cache-Updated-At`: when the cache was last refreshed - `X-Cache-Age-Seconds`: how stale the data is (max ~600s) - `X-Cache-Stale: true` if pg_cron missed its window ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/v1/iocs/stats openapi: 3.0.3 info: title: SOC Defenders Threat Intelligence API description: >- # Overview The SOC Defenders Threat Intelligence API provides programmatic access to aggregated threat intelligence from 30+ cybersecurity sources. Export IOCs (Indicators of Compromise) in various formats including JSON, CSV, STIX 2.1, MISP, CEF, and OpenIOC. ## Authentication All API endpoints require authentication using an API key. Include your key in one of these ways: - **Authorization Header** (recommended): `Authorization: Bearer sk_live_xxx` - **X-API-Key Header**: `X-API-Key: sk_live_xxx` - **Query Parameter**: `?api_key=sk_live_xxx` ## Rate Limiting Rate limits vary by tier. When limits are exceeded, the API returns a 429 status code. | Tier | Requests/min | Requests/day | Lookback | Formats | |------|-------------|--------------|----------|---------| | Free | 10 | 1,000 | 1 day | JSON / CSV | | Pro ($299/mo) | 1,000 | 1,000,000 | 365 days | All (STIX, TAXII, MISP, CEF, OpenIOC, Sigma) | Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests per minute - `X-RateLimit-Remaining`: Requests remaining in current window - `X-RateLimit-Reset`: Unix timestamp when the limit resets ## Error Handling All errors follow a consistent format: ```json { "error": { "code": "error_code", "message": "Human readable message", "details": {}, "request_id": "req_abc123" } } ``` ## STIX/TAXII Support For STIX 2.1 and TAXII 2.1 integration, see the TAXII endpoints section. TAXII endpoints are available at `/api/taxii2/`. version: 1.0.0 contact: name: SOC Defenders Support url: https://socdefenders.ai/contact email: support@socdefenders.ai license: name: Proprietary url: https://socdefenders.ai/terms servers: - url: https://socdefenders.ai description: Production server security: [] tags: - name: IOCs description: Indicators of Compromise endpoints - name: Statistics description: Feed and IOC statistics - name: API Keys description: API key management (requires session auth) - name: TAXII description: TAXII 2.1 threat intelligence sharing endpoints - name: Export Formats description: Specialized export format endpoints (MISP, CEF, OpenIOC) - name: Articles description: >- Aggregated news articles from 30+ cybersecurity sources, with rich filtering and bulk-export support - name: Lookup description: >- Single-IOC enrichment lookup. Auto-detects type, aggregates reporting sources, returns AI risk + MITRE techniques + hunting queries. Free-tier friendly. - name: Detection Rules description: >- Generate ready-to-deploy SIEM detection rules from recent IOCs. Sigma rules ship as multi-document YAML covering network / DNS / proxy / process_creation logsources. paths: /api/v1/iocs/stats: get: tags: - Statistics summary: Aggregated IOC statistics and trends description: >- Pre-computed aggregations over the entire IOC corpus. Backed by the `iocs_stats_cache` table (refreshed every 10 minutes via pg_cron) — sub-millisecond response time. ## What you get - Total IOC count and total article count - Breakdown by IOC type (ipv4, domain, hash, etc.) - Breakdown by source feed - Breakdown by category (news, research, threat-intel, vendor, government) - Last 24h and last 7d trend - Feed health (healthy / degraded / error) - Top MITRE ATT&CK techniques - Top CVEs ## Use cases - **Dashboard tiles**: "23,541 indicators ingested in the last 24h" - **Trend charts**: 7-day rolling counts for sparklines - **Coverage analysis**: which sources contribute most volume - **Health monitoring**: detect when a feed stops producing IOCs ## Cache headers Response includes: - `X-Cache-Updated-At`: when the cache was last refreshed - `X-Cache-Age-Seconds`: how stale the data is (max ~600s) - `X-Cache-Stale: true` if pg_cron missed its window operationId: getIOCStats responses: '200': description: IOC statistics (cache-backed, sub-millisecond response) headers: X-Cache-Updated-At: description: When the cache was last refreshed schema: type: string format: date-time X-Cache-Age-Seconds: description: How old the cached data is schema: type: integer content: application/json: schema: $ref: '#/components/schemas/StatsResponse' example: meta: generated_at: '2026-05-17T10:30:00Z' cache_updated_at: '2026-05-17T10:25:00Z' cache_age_seconds: 300 feed_version: '1.0' source: SOC Defenders data: totalIOCs: 1351663 totalArticles: 21121 byType: ipv4: 423891 ipv6: 12450 domain: 287654 url: 198432 sha256: 234812 md5: 89345 sha1: 67234 email: 23456 cve: 5611 mitre_attack: 8778 bySource: URLhaus: 412908 Feodo Tracker: 234567 ThreatFox: 198765 BleepingComputer: 56789 Krebs on Security: 23456 byCategory: threat-intel: 891234 news: 234561 research: 145678 vendor: 56781 government: 23409 last24h: newIOCs: 18432 newArticles: 287 byType: ipv4: 5432 domain: 4321 sha256: 3210 url: 2876 last7d: newIOCs: 134567 newArticles: 2034 trend: - 18234 - 19102 - 17654 - 21345 - 18432 - 19876 - 19924 feedHealth: total: 84 healthy: 78 degraded: 4 error: 2 topMitreTechniques: - id: T1566 count: 1234 - id: T1059 count: 987 - id: T1190 count: 845 topCVEs: - id: CVE-2026-12345 count: 234 - id: CVE-2026-9999 count: 187 lastUpdated: '2026-05-17T10:25:00Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: cURL label: Fetch stats source: |- curl -H "Authorization: Bearer sk_live_..." \ "https://socdefenders.ai/api/v1/iocs/stats" components: schemas: StatsResponse: type: object properties: meta: type: object data: type: object properties: total_iocs: type: integer by_type: type: object additionalProperties: type: integer by_category: type: object additionalProperties: type: integer by_confidence: type: object additionalProperties: type: integer last_24h: type: object properties: new_iocs: type: integer new_articles: type: integer last_7d: type: object properties: new_iocs: type: integer new_articles: type: integer trend: type: string enum: - up - down - stable sources: type: object properties: total: type: integer active: type: integer last_fetch: type: string format: date-time nullable: true top_mitre_techniques: type: array items: type: object properties: id: type: string count: type: integer top_cves: type: array items: type: object properties: id: type: string count: type: integer Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code for programmatic handling message: type: string description: Human-readable error message details: type: object description: Additional error details request_id: type: string description: Unique request identifier for support responses: Unauthorized: description: Authentication required or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: missing_api_key message: >- API key is required. Include it in the Authorization header as "Bearer sk_live_..." request_id: req_abc123 Forbidden: description: Insufficient permissions or scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope message: This endpoint requires the "read:stix" scope details: required_scope: read:stix your_scopes: - read:iocs upgrade_url: https://socdefenders.ai/export#pricing request_id: req_abc123 RateLimitExceeded: description: Rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Rate limit ceiling schema: type: integer X-RateLimit-Remaining: description: Remaining requests (will be 0) schema: type: integer X-RateLimit-Reset: description: Unix timestamp when limit resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: Rate limit exceeded. Please wait before making more requests. details: limit: 10 reset_at: '2024-12-09T10:31:00Z' tier: free upgrade_url: https://socdefenders.ai/export#pricing request_id: req_abc123 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key in X-API-Key header BearerAuth: type: http scheme: bearer description: 'API key in Authorization header: `Authorization: Bearer sk_live_xxx`' ````