> ## 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. # Usage analytics and rate-limit budget for an API key > Detailed usage analytics for a specific API key, scoped to the authenticated user. Use this to: - Detect runaway clients (which endpoint is burning your rate limit) - Forecast tier upgrades (am I approaching the daily cap?) - Triage support issues (what does my 4xx rate look like?) - Bill teammates (per-key request volume) ## What's returned - Request counts: total, successful (2xx/3xx), client error (4xx), server error (5xx) - Success rate and average response time - Latency percentiles: p50, p95, p99 - Rate limit usage: per-minute and per-day high-water mark - Top endpoints by request count - Status code distribution - Daily time-series for the requested window - 429 (rate-limit) breakdown by hour This endpoint authenticates via session cookie (browser/UI), not API key. Use it from the SOC Defenders dashboard or a logged-in fetch. ## OpenAPI ````yaml https://socdefenders.ai/api/openapi.json get /api/v1/keys/{keyId}/usage 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/keys/{keyId}/usage: get: tags: - API Keys summary: Usage analytics and rate-limit budget for an API key description: >- Detailed usage analytics for a specific API key, scoped to the authenticated user. Use this to: - Detect runaway clients (which endpoint is burning your rate limit) - Forecast tier upgrades (am I approaching the daily cap?) - Triage support issues (what does my 4xx rate look like?) - Bill teammates (per-key request volume) ## What's returned - Request counts: total, successful (2xx/3xx), client error (4xx), server error (5xx) - Success rate and average response time - Latency percentiles: p50, p95, p99 - Rate limit usage: per-minute and per-day high-water mark - Top endpoints by request count - Status code distribution - Daily time-series for the requested window - 429 (rate-limit) breakdown by hour This endpoint authenticates via session cookie (browser/UI), not API key. Use it from the SOC Defenders dashboard or a logged-in fetch. operationId: getAPIKeyUsage parameters: - name: keyId in: path required: true description: API key ID (UUID from the list endpoint) schema: type: string format: uuid example: 00000000-0000-4000-8000-000000000123 - name: days in: query description: >- Lookback window in days (1–90). The time-series in the response has one bucket per day. schema: type: integer minimum: 1 maximum: 90 default: 7 example: 30 responses: '200': description: Usage statistics for the requested key content: application/json: schema: $ref: '#/components/schemas/APIKeyUsageStats' example: data: key_id: 00000000-0000-4000-8000-000000000123 window_days: 30 total_requests: 142587 successful: 139214 client_errors: 3128 server_errors: 245 success_rate: 0.9763 avg_response_time_ms: 287 latency_p50_ms: 195 latency_p95_ms: 612 latency_p99_ms: 1240 rate_limit_peak_per_minute: 87 rate_limit_peak_per_day: 8430 top_endpoints: - path: /api/v1/articles count: 89234 - path: /api/v1/iocs count: 38765 - path: /api/v1/lookup count: 14588 by_status: '200': 139214 '400': 1245 '401': 12 '403': 89 '404': 1576 '429': 206 '500': 245 daily: - date: '2026-05-16' requests: 4823 errors: 67 - date: '2026-05-15' requests: 5102 errors: 89 rate_limit_hits_by_hour: - hour: '2026-05-16T14:00:00Z' count: 12 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' security: - CookieAuth: [] x-codeSamples: - lang: JavaScript label: Fetch from logged-in browser source: >- // Session-cookie auth — make sure you're logged in to socdefenders.ai const r = await fetch('/api/v1/keys//usage?days=30', { credentials: 'include' }); const { data } = await r.json(); console.log(`p95 latency: ${data.latency_p95_ms}ms`); console.log(`Daily peak: ${data.rate_limit_peak_per_day} requests`); components: schemas: APIKeyUsageStats: type: object properties: data: type: object properties: key: type: object properties: id: type: string format: uuid name: type: string tier: type: string enum: - free - pro period: type: object properties: days: type: integer start: type: string format: date-time end: type: string format: date-time summary: type: object properties: totalRequests: type: integer description: Total API requests in period successfulRequests: type: integer description: Requests with 2xx/3xx status failedRequests: type: integer description: Requests with 4xx/5xx status successRate: type: number description: Success rate as percentage (0-100) avgResponseTime: type: integer description: Average response time in milliseconds totalIOCsReturned: type: integer description: Total IOCs returned across all requests latencyPercentiles: type: object description: Response time percentiles in milliseconds properties: p50: type: integer description: Median response time p95: type: integer description: 95th percentile response time p99: type: integer description: 99th percentile response time rateLimits: type: object properties: perMinute: type: object properties: limit: type: integer current: type: integer remaining: type: integer percentUsed: type: number perDay: type: object properties: limit: type: integer current: type: integer remaining: type: integer percentUsed: type: number rateLimitHits: type: object description: 429 rate limit responses breakdown properties: total: type: integer description: Total 429 responses byEndpoint: type: array items: type: object properties: endpoint: type: string count: type: integer breakdown: type: object properties: byEndpoint: type: array items: type: object properties: endpoint: type: string count: type: integer avgTime: type: integer errors: type: integer errorRate: type: number byStatusCode: type: array items: type: object properties: statusCode: type: integer count: type: integer percentage: type: number timeSeries: type: array items: type: object properties: date: type: string format: date requests: type: integer errors: 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 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: The requested resource was not found request_id: req_abc123 securitySchemes: CookieAuth: type: apiKey in: cookie name: sb-access-token description: Session cookie (for API key management endpoints) ````