Last updated: Jul 25, 2025, 10:08 AM UTC

Product Requirements Document: Usage API

Generated: 2025-01-24
Status: Draft
Verified:

Executive Summary

The Usage API provides programmatic access to conversion usage statistics, replacing traditional web dashboards with an API-first approach. This enables users to integrate usage data into their own systems, create custom dashboards, and automate usage monitoring.

Product Overview

Purpose

Provide comprehensive usage statistics and analytics via RESTful API endpoints, enabling users to track their conversion usage, monitor trends, and manage their quotas programmatically.

Target Users

  • Developers integrating conversion services
  • DevOps teams monitoring usage
  • Finance teams tracking costs
  • Product teams analyzing conversion patterns

User Stories

Developer Stories

  • As a developer, I want to check my current usage to avoid hitting limits
  • As a developer, I want to retrieve historical usage data for reporting
  • As a developer, I want to monitor usage trends programmatically
  • As a developer, I want to export usage data to my own analytics systems

Operations Stories

  • As an ops engineer, I want to set up alerts when usage approaches limits
  • As an ops engineer, I want to monitor conversion success rates
  • As an ops engineer, I want to track performance metrics

Business Stories

  • As a product manager, I want to analyze conversion patterns by file type
  • As a finance manager, I want to forecast usage and costs
  • As a team lead, I want to distribute usage across multiple API keys

Core Features

1. Usage Summary Endpoint

GET /api/usage/summary
Authorization: Bearer {API_KEY}

Response:
{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z",
    "timezone": "UTC"
  },
  "subscription": {
    "plan": "pro",
    "status": "active",
    "renewed_at": "2025-01-01T00:00:00Z",
    "expires_at": "2025-02-01T00:00:00Z"
  },
  "usage": {
    "conversions": {
      "used": 3847,
      "limit": 10000,
      "percentage": 38.47,
      "remaining": 6153
    },
    "storage": {
      "bytes_processed": 487293847,
      "mb_processed": 464.7,
      "largest_file_mb": 47.3
    }
  },
  "current_rate": {
    "daily_average": 124,
    "projected_monthly": 3720,
    "days_until_limit": 49
  }
}

2. Detailed Usage History

GET /api/usage/history?start_date=2025-01-01&end_date=2025-01-31&granularity=daily
Authorization: Bearer {API_KEY}

Response:
{
  "period": {
    "start": "2025-01-01",
    "end": "2025-01-31",
    "granularity": "daily"
  },
  "data": [
    {
      "date": "2025-01-23",
      "conversions": {
        "total": 156,
        "successful": 152,
        "failed": 4,
        "by_type": {
          "xlsx-to-json": 67,
          "pdf-to-md": 45,
          "docx-to-html": 23,
          "docx-to-md": 21
        }
      },
      "performance": {
        "average_processing_time_ms": 1832,
        "p95_processing_time_ms": 3421,
        "average_file_size_kb": 823
      }
    }
    // ... more daily entries
  ],
  "totals": {
    "conversions": 3847,
    "success_rate": 97.3,
    "average_daily": 124
  }
}

3. Real-time Usage Metrics

GET /api/usage/current
Authorization: Bearer {API_KEY}

Response:
{
  "timestamp": "2025-01-24T14:32:18Z",
  "today": {
    "conversions": 87,
    "last_conversion": "2025-01-24T14:28:33Z",
    "success_rate": 98.8
  },
  "last_hour": {
    "conversions": 12,
    "average_processing_time_ms": 1654
  },
  "quota_status": {
    "percentage_used": 38.47,
    "alert_threshold": 80,
    "alert_active": false
  }
}

4. Usage Breakdown by File Type

GET /api/usage/breakdown?period=current_month
Authorization: Bearer {API_KEY}

Response:
{
  "period": "2025-01",
  "breakdown": {
    "by_format": {
      "excel": {
        "conversions": 1923,
        "percentage": 50.0,
        "subtypes": {
          "xlsx": 1654,
          "xls": 198,
          "xlsm": 71
        }
      },
      "pdf": {
        "conversions": 1154,
        "percentage": 30.0
      },
      "word": {
        "conversions": 770,
        "percentage": 20.0,
        "subtypes": {
          "docx": 698,
          "dotx": 45,
          "dotm": 27
        }
      }
    },
    "by_output": {
      "json": 1654,
      "markdown": 1539,
      "html": 654
    }
  }
}

5. Performance Analytics

GET /api/usage/performance?period=last_7_days
Authorization: Bearer {API_KEY}

Response:
{
  "period": {
    "start": "2025-01-17",
    "end": "2025-01-24"
  },
  "performance": {
    "processing_times": {
      "average_ms": 1847,
      "median_ms": 1523,
      "p95_ms": 3892,
      "p99_ms": 7234
    },
    "file_sizes": {
      "average_kb": 892,
      "median_kb": 456,
      "largest_mb": 47.8
    },
    "success_metrics": {
      "total_attempts": 872,
      "successful": 847,
      "failed": 25,
      "success_rate": 97.1
    },
    "error_breakdown": {
      "file_too_large": 12,
      "invalid_format": 8,
      "processing_timeout": 5
    }
  }
}

6. Usage Alerts Configuration

POST /api/usage/alerts
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "alerts": [
    {
      "type": "quota_threshold",
      "threshold": 80,
      "enabled": true,
      "notify_email": true
    },
    {
      "type": "daily_limit",
      "threshold": 500,
      "enabled": true
    },
    {
      "type": "error_rate",
      "threshold": 5,
      "window_minutes": 60,
      "enabled": true
    }
  ]
}

Response:
{
  "status": "configured",
  "alerts": [
    {
      "id": "alert_quota_80",
      "type": "quota_threshold",
      "threshold": 80,
      "status": "active",
      "last_triggered": null
    }
  ]
}

7. Export Usage Data

GET /api/usage/export?format=csv&period=last_month
Authorization: Bearer {API_KEY}

Response Headers:
Content-Type: text/csv
Content-Disposition: attachment; filename="usage_2024-12.csv"

Response Body:
Date,Conversions,Excel,PDF,Word,Success_Rate,Avg_Processing_MS
2024-12-01,145,72,43,30,98.6,1823
2024-12-02,167,84,51,32,97.0,1967
...

Technical Architecture

API Design Principles

graph TD A[Client Request] --> B[API Gateway] B --> C[Authentication] C --> D[Rate Limiting] D --> E[Usage API Service] E --> F[Usage Database] E --> G[Analytics Engine] E --> H[Cache Layer] F --> I[Response Builder] G --> I H --> I I --> J[JSON Response]

Data Flow

sequenceDiagram participant Client participant API participant Auth participant UsageDB participant Cache Client->>API: GET /api/usage/summary API->>Auth: Validate API Key Auth->>API: User ID & Plan API->>Cache: Check cached data Cache-->>API: Cache miss API->>UsageDB: Query usage data UsageDB->>API: Raw usage records API->>API: Calculate metrics API->>Cache: Store results API->>Client: JSON response

Implementation Details

Database Schema

-- Usage tracking table
CREATE TABLE usage_records (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    api_key_id UUID NOT NULL,
    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
    endpoint VARCHAR(50) NOT NULL,
    file_type VARCHAR(20) NOT NULL,
    file_size_bytes BIGINT NOT NULL,
    processing_time_ms INT NOT NULL,
    success BOOLEAN NOT NULL,
    error_code VARCHAR(50),
    output_format VARCHAR(20) NOT NULL,
    token_count INT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Aggregated daily stats (for performance)
CREATE TABLE usage_daily_stats (
    user_id UUID NOT NULL,
    date DATE NOT NULL,
    total_conversions INT NOT NULL,
    successful_conversions INT NOT NULL,
    failed_conversions INT NOT NULL,
    total_bytes_processed BIGINT NOT NULL,
    avg_processing_time_ms INT NOT NULL,
    PRIMARY KEY (user_id, date)
);

-- Alert configurations
CREATE TABLE usage_alerts (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    alert_type VARCHAR(50) NOT NULL,
    threshold DECIMAL NOT NULL,
    enabled BOOLEAN DEFAULT true,
    notify_email BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

API Implementation

// Usage summary endpoint
app.get('/api/usage/summary', authenticate, async (req, res) => {
  const userId = req.user.id;
  const currentPeriod = getCurrentBillingPeriod(req.user.subscription);
  
  // Check cache first
  const cacheKey = `usage:summary:${userId}:${currentPeriod.start}`;
  const cached = await redis.get(cacheKey);
  if (cached) {
    return res.json(JSON.parse(cached));
  }
  
  // Query usage data
  const usage = await db.query(`
    SELECT 
      COUNT(*) as total_conversions,
      SUM(CASE WHEN success = true THEN 1 ELSE 0 END) as successful,
      SUM(file_size_bytes) as bytes_processed,
      MAX(file_size_bytes) as largest_file
    FROM usage_records
    WHERE user_id = $1 
      AND timestamp >= $2 
      AND timestamp < $3
  `, [userId, currentPeriod.start, currentPeriod.end]);
  
  // Calculate current rate
  const daysSoFar = getDaysSinceStart(currentPeriod.start);
  const dailyAverage = Math.round(usage.total_conversions / daysSoFar);
  const projectedMonthly = dailyAverage * 30;
  
  const response = {
    period: currentPeriod,
    subscription: {
      plan: req.user.subscription.plan,
      status: req.user.subscription.status,
      renewed_at: req.user.subscription.renewed_at,
      expires_at: req.user.subscription.expires_at
    },
    usage: {
      conversions: {
        used: usage.total_conversions,
        limit: getMonthlyLimit(req.user.subscription.plan),
        percentage: (usage.total_conversions / getMonthlyLimit(req.user.subscription.plan)) * 100,
        remaining: getMonthlyLimit(req.user.subscription.plan) - usage.total_conversions
      },
      storage: {
        bytes_processed: usage.bytes_processed,
        mb_processed: (usage.bytes_processed / 1024 / 1024).toFixed(1),
        largest_file_mb: (usage.largest_file / 1024 / 1024).toFixed(1)
      }
    },
    current_rate: {
      daily_average: dailyAverage,
      projected_monthly: projectedMonthly,
      days_until_limit: Math.floor((getMonthlyLimit(req.user.subscription.plan) - usage.total_conversions) / dailyAverage)
    }
  };
  
  // Cache for 5 minutes
  await redis.setex(cacheKey, 300, JSON.stringify(response));
  
  res.json(response);
});

Security Considerations

Authentication

  • API key required for all endpoints
  • Keys tied to specific user accounts
  • Rate limiting per API key

Data Privacy

  • Users can only access their own usage data
  • No cross-user data exposure
  • Audit logs for all API access

Performance

  • Aggressive caching for frequently accessed data
  • Daily aggregation tables for historical queries
  • Pagination for large result sets

Integration Examples

JavaScript/Node.js

const ConvertToMarkdownAPI = require('@knowcode/convert-to-markdown');

const api = new ConvertToMarkdownAPI({
  apiKey: 'your-api-key'
});

// Get current usage
const usage = await api.usage.getSummary();
console.log(`Used ${usage.usage.conversions.used} of ${usage.usage.conversions.limit} conversions`);

// Set up alert
await api.usage.configureAlert({
  type: 'quota_threshold',
  threshold: 80,
  enabled: true
});

// Export last month's data
const csvData = await api.usage.export({
  format: 'csv',
  period: 'last_month'
});

Python

import requests
from datetime import datetime, timedelta

class ConvertToMarkdownUsage:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://convert-to-markdown.knowcode.tech/api'
        
    def get_summary(self):
        response = requests.get(
            f'{self.base_url}/usage/summary',
            headers={'Authorization': f'Bearer {self.api_key}'}
        )
        return response.json()
    
    def get_history(self, days=7):
        end_date = datetime.now()
        start_date = end_date - timedelta(days=days)
        
        response = requests.get(
            f'{self.base_url}/usage/history',
            params={
                'start_date': start_date.strftime('%Y-%m-%d'),
                'end_date': end_date.strftime('%Y-%m-%d'),
                'granularity': 'daily'
            },
            headers={'Authorization': f'Bearer {self.api_key}'}
        )
        return response.json()

# Usage
api = ConvertToMarkdownUsage('your-api-key')
usage = api.get_summary()
print(f"Current usage: {usage['usage']['conversions']['percentage']}%")

Monitoring Integration

# Prometheus configuration
- job_name: 'convert-to-markdown-usage'
  scrape_interval: 60s
  bearer_token: 'your-api-key'
  static_configs:
    - targets: ['convert-to-markdown.knowcode.tech']
  metrics_path: '/api/usage/metrics'
  
# Grafana dashboard query
sum(convert_to_markdown_conversions_total) by (file_type)

Pricing Tiers

Free Tier

  • Basic usage summary (current month only)
  • Daily granularity
  • No historical data
  • No export functionality

Pro Tier ($10/month)

  • Full API access
  • Historical data (12 months retention)
  • Hourly granularity available
  • Export in CSV/JSON formats
  • Custom alerts
  • Performance analytics
  • Real-time metrics

Enterprise

  • Custom data retention
  • Sub-minute granularity
  • Custom metrics
  • Dedicated support
  • SLA guarantees

Success Metrics

Adoption

  • 80% of Pro users accessing Usage API within first month
  • Average of 50 API calls per user per month
  • 30% of users setting up alerts

Performance

  • API response time < 200ms for summary endpoint
  • 99.9% API availability
  • Cache hit rate > 80%

Business Impact

  • 25% reduction in support tickets about usage
  • Increased Pro tier retention due to better visibility
  • Enable partner integrations through usage data

Roadmap

Phase 1 (MVP)

  • Basic usage summary endpoint
  • Daily history for current month
  • Simple authentication

Phase 2

  • Historical data with pagination
  • Performance analytics
  • CSV export

Phase 3

  • Real-time usage streaming
  • Custom alerts and webhooks
  • Advanced analytics

Phase 4

  • Predictive usage forecasting
  • Cost optimization recommendations
  • Team usage breakdown

Conclusion

The Usage API transforms usage tracking from a static dashboard into a powerful, programmable interface that enables users to integrate conversion usage data into their workflows. This API-first approach aligns with modern development practices and provides the flexibility users need to build custom solutions on top of our conversion service.