Overview

The usage endpoint provides comprehensive analytics about your API consumption, including conversion statistics, billing information, format breakdowns, and usage trends. Use this data to optimize your integration and monitor costs.

📊 Detailed Analytics

Get comprehensive usage statistics by format, time period, and user.

💰 Billing Insights

Monitor current charges, overages, and billing cycle information.

📈 Trend Analysis

Track usage patterns and identify growth trends over time.

Query Parameters

Parameter	Type	Default	Description
period	string	current	Time period (current, YYYY-MM, YYYY)
start_date	string	-	Start date for custom range (YYYY-MM-DD)
end_date	string	-	End date for custom range (YYYY-MM-DD)
granularity	string	daily	Data granularity (hourly, daily, monthly)
format	string	-	Filter by file format (pdf, docx, pptx, etc.)

Parameter Examples

• period=current - Current billing period
• period=2024-01 - January 2024
• period=2023 - Year 2023
• start_date=2024-01-01&end_date=2024-01-15 - Custom date range
• granularity=hourly - Hourly breakdown (max 7 days)

Request Examples

Current Period Usage

Current Billing Period

curl -X GET "https://api.markdownconverters.com/api/v1/usage?period=current" \
 -H "X-API-Key: your_api_key_here"

Historical Data

November 2023 Daily Breakdown

curl -X GET "https://api.markdownconverters.com/api/v1/usage?period=2023-11&granularity=daily" \
 -H "X-API-Key: your_api_key_here"

Custom Date Range

Custom Range with Hourly Data

curl -X GET "https://api.markdownconverters.com/api/v1/usage?start_date=2024-01-01&end_date=2024-01-15&granularity=hourly" \
 -H "X-API-Key: your_api_key_here"

Response Examples

Current Period Response

Detailed Usage Statistics (200 OK)

{
 "period": {
 "start": "2024-01-01T00:00:00Z",
 "end": "2024-01-31T23:59:59Z",
 "type": "monthly"
 },
 "usage": {
 "total_conversions": 15420,
 "successful_conversions": 14891,
 "failed_conversions": 529,
 "success_rate": 0.966,
 "total_pages_processed": 98765,
 "total_file_size_mb": 5234.7
 },
 "usage_by_format": {
 "pdf": {
 "conversions": 8934,
 "pages": 67543,
 "avg_processing_time_ms": 3247
 },
 "docx": {
 "conversions": 4521,
 "pages": 18976,
 "avg_processing_time_ms": 1834
 },
 "pptx": {
 "conversions": 1965,
 "pages": 12246,
 "avg_processing_time_ms": 2156
 }
 },
 "daily_breakdown": [
 {
 "date": "2024-01-01",
 "conversions": 456,
 "pages": 2834,
 "file_size_mb": 234.5
 },
 {
 "date": "2024-01-02", 
 "conversions": 523,
 "pages": 3201,
 "file_size_mb": 287.3
 }
 ],
 "api_limits": {
 "monthly_conversion_limit": 50000,
 "monthly_conversions_used": 15420,
 "monthly_conversions_remaining": 34580,
 "daily_conversion_limit": 2000,
 "daily_conversions_used": 234,
 "daily_conversions_remaining": 1766,
 "max_file_size_mb": 50,
 "max_batch_size": 25
 },
 "billing": {
 "plan": "professional",
 "billing_cycle": "monthly",
 "next_billing_date": "2024-02-01T00:00:00Z",
 "current_charges": 89.50,
 "overage_charges": 12.30
 },
 "top_users": [
 {
 "conversions": 2341,
 "pages": 15678,
 "success_rate": 0.987
 },
 {
 "conversions": 1823,
 "pages": 12456,
 "success_rate": 0.954
 }
 ]
}

Historical Data Response

Historical Analytics (200 OK)

{
 "period": {
 "start": "2023-01-01T00:00:00Z",
 "end": "2023-12-31T23:59:59Z",
 "type": "yearly"
 },
 "monthly_summary": [
 {
 "month": "2023-01",
 "conversions": 12456,
 "pages": 78934,
 "file_size_mb": 4123.5,
 "success_rate": 0.962,
 "avg_processing_time_ms": 2456
 },
 {
 "month": "2023-02",
 "conversions": 14789,
 "pages": 89123,
 "file_size_mb": 4687.2,
 "success_rate": 0.971,
 "avg_processing_time_ms": 2234
 }
 ],
 "year_totals": {
 "total_conversions": 185467,
 "total_pages": 1245789,
 "total_file_size_mb": 65432.1,
 "avg_success_rate": 0.968,
 "peak_month": "2023-11",
 "peak_month_conversions": 18923
 },
 "trends": {
 "conversion_growth_rate": 0.234,
 "avg_file_size_trend": "increasing",
 "most_popular_format": "pdf",
 "fastest_growing_format": "pptx"
 }
}

Response Fields

Usage Statistics

Field	Type	Description
total_conversions	number	Total number of conversion attempts
successful_conversions	number	Number of successful conversions
failed_conversions	number	Number of failed conversions
success_rate	number	Success rate as decimal (0.0-1.0)
total_pages_processed	number	Total number of pages converted
total_file_size_mb	number	Total file size processed in MB

API Limits

Field	Type	Description
monthly_conversion_limit	number	Maximum conversions per month
monthly_conversions_used	number	Conversions used this month
monthly_conversions_remaining	number	Conversions remaining this month
daily_conversion_limit	number	Maximum conversions per month

Billing Information

Field	Type	Description
plan	string	Current subscription plan
billing_cycle	string	Billing frequency (monthly, yearly)
next_billing_date	string	Next billing date (ISO 8601)
current_charges	number	Current period charges in USD
overage_charges	number	Overage charges in USD

Common Use Cases

Usage Monitoring

• Track API consumption against limits
• Monitor success rates and identify issues
• Analyze usage patterns by format
• Set up alerts for approaching limits

Billing & Optimization

• Predict monthly charges based on usage
• Optimize file processing to reduce costs
• Identify peak usage periods
• Track ROI on different document types

Usage Analytics