Back to API Docs

Usage Tracking

Monitor your API consumption with per-request logs and aggregated summaries. Track request counts, processing times, file sizes, OCR page usage, and costs across all endpoints.

Per-Request Usage Logs

GEThttps://app.alternapdf.com/api/v1/usage

Returns a paginated list of individual API requests with timestamps, endpoints, status codes, processing times, and file sizes.

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoMax records to return. Default: 100
offsetintegerNoNumber of records to skip for pagination. Default: 0

Code Examples

cURL
curl -X GET "https://app.alternapdf.com/api/v1/usage?limit=100&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"
Python
import requests

url = "https://app.alternapdf.com/api/v1/usage"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params)
result = response.json()

for record in result["usage"]:
    print(f"{record['timestamp']} | {record['endpoint']} | "
          f"{record['status_code']} | {record['processing_time_ms']}ms")

print(f"\nTotal records: {result['total']}")
JavaScript
const response = await fetch(
  "https://app.alternapdf.com/api/v1/usage?limit=100&offset=0",
  {
    headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

const result = await response.json();

for (const record of result.usage) {
  console.log(
    `${record.timestamp} | ${record.endpoint} | ` +
    `${record.status_code} | ${record.processing_time_ms}ms`
  );
}

console.log(`\nTotal records: ${result.total}`);

Response

JSON Response
{
  "usage": [
    {
      "id": "req_a1b2c3d4",
      "timestamp": "2024-01-15T14:32:10Z",
      "endpoint": "/api/v1/convert/html-to-pdf",
      "method": "POST",
      "status_code": 200,
      "processing_time_ms": 1850,
      "file_size_bytes": 245760,
      "credits_used": 1
    },
    {
      "id": "req_e5f6g7h8",
      "timestamp": "2024-01-15T14:28:45Z",
      "endpoint": "/api/v1/ocr/extract/vision",
      "method": "POST",
      "status_code": 200,
      "processing_time_ms": 4200,
      "file_size_bytes": 1048576,
      "credits_used": 3
    },
    {
      "id": "req_i9j0k1l2",
      "timestamp": "2024-01-15T14:15:22Z",
      "endpoint": "/api/v1/ocr/extract/simple",
      "method": "POST",
      "status_code": 422,
      "processing_time_ms": 120,
      "file_size_bytes": 0,
      "credits_used": 0
    }
  ],
  "total": 1542,
  "limit": 100,
  "offset": 0
}

Aggregated Usage Summary

GEThttps://app.alternapdf.com/api/v1/usage/summary

Returns aggregated usage statistics over a time period. Includes total requests, success/failure breakdown, processing times, file sizes, OCR pages, costs, and per-endpoint request counts.

Query Parameters

ParameterTypeRequiredDescription
daysintegerNoNumber of days to aggregate. Default: 30

Code Examples

cURL
curl -X GET "https://app.alternapdf.com/api/v1/usage/summary?days=30" \
  -H "X-API-Key: YOUR_API_KEY"
Python
import requests

url = "https://app.alternapdf.com/api/v1/usage/summary"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"days": 30}

response = requests.get(url, headers=headers, params=params)
summary = response.json()

print(f"Total requests: {summary['total_requests']}")
print(f"Successful: {summary['successful_requests']}")
print(f"Failed: {summary['failed_requests']}")
print(f"Avg processing time: {summary['average_processing_time_ms']}ms")
print(f"Total OCR pages: {summary['total_ocr_pages']}")
print(f"Total OCR cost: ${summary['total_ocr_cost_usd']:.2f}")

print("\nRequests by endpoint:")
for endpoint, count in summary["endpoints"].items():
    print(f"  {endpoint}: {count}")
JavaScript
const response = await fetch(
  "https://app.alternapdf.com/api/v1/usage/summary?days=30",
  {
    headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

const summary = await response.json();

console.log(`Total requests: ${summary.total_requests}`);
console.log(`Successful: ${summary.successful_requests}`);
console.log(`Failed: ${summary.failed_requests}`);
console.log(`Avg processing time: ${summary.average_processing_time_ms}ms`);
console.log(`Total OCR pages: ${summary.total_ocr_pages}`);
console.log(`Total OCR cost: $${summary.total_ocr_cost_usd.toFixed(2)}`);

console.log("\nRequests by endpoint:");
for (const [endpoint, count] of Object.entries(summary.endpoints)) {
  console.log(`  ${endpoint}: ${count}`);
}

Response

JSON Response
{
  "total_requests": 2847,
  "successful_requests": 2791,
  "failed_requests": 56,
  "total_processing_time_ms": 4250000,
  "average_processing_time_ms": 1493,
  "total_file_size_bytes": 8573952000,
  "total_ocr_pages": 1240,
  "total_ocr_cost_usd": 8.45,
  "endpoints": {
    "/api/v1/convert/html-to-pdf": 680,
    "/api/v1/convert/text-to-pdf": 412,
    "/api/v1/convert/markdown-to-pdf": 295,
    "/api/v1/convert/json-to-pdf": 148,
    "/api/v1/ocr/extract/simple": 520,
    "/api/v1/ocr/extract/advanced": 310,
    "/api/v1/ocr/extract/vision": 185,
    "/api/v1/pdf/merge": 112,
    "/api/v1/pdf/split": 89,
    "/api/v1/convert/pdf-to-text": 62,
    "/api/v1/convert/pdf-to-html": 34
  }
}

Response Fields

FieldTypeDescription
total_requestsintegerTotal number of API requests in the period
successful_requestsintegerRequests that returned 2xx status codes
failed_requestsintegerRequests that returned 4xx or 5xx status codes
total_processing_time_msintegerSum of all processing times in milliseconds
average_processing_time_msintegerAverage processing time per request
total_file_size_bytesintegerTotal bytes of files processed
total_ocr_pagesintegerTotal pages processed by OCR endpoints
total_ocr_cost_usdfloatTotal Vision OCR cost in USD (Sonnet/Haiku usage)
endpointsobjectRequest count per endpoint path