Aıon

Documentation

Usage Analytics API Reference

Monitor API usage, plan utilization, and performance metrics

Rate Limited

Usage analytics endpoints are rate limited to 30 requests per minute, except for the usage check endpoint which allows 60 requests per minute.

Usage Summary

GET/api/v2/usage/summary

Get aggregated usage statistics for the authenticated tenant. Supports filtering by date range, predefined period, or specific API key. Requires VIEW permission. Rate limit: 30/min.

Request

// Query parameters:
?start_date=2025-01-01T00:00:00Z   // optional - Start date for usage period
&end_date=2025-01-31T23:59:59Z     // optional - End date for usage period
&period=month                       // optional - Predefined period: day, week, month (default: month)
&api_key_id=uuid                    // optional - Filter by specific API key

Response

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "usage": {
    "verify_count": 120,
    "describe_count": 3500,
    "batch_count": 45,
    "total_requests": 3665,
    "successful_requests": 3600,
    "failed_requests": 65
  },
  "performance": {
    "avg_response_time_ms": 245.5
  },
  "limits": {
    "monthly_limit": 100000,
    "used_this_month": 3665,
    "remaining": 96335,
    "percentage_used": 3.67
  },
  "plan": {
    "name": "Professional",
    "requests_limit": 100000,
    "requests_used": 3665,
    "requests_remaining": 96335,
    "usage_percentage": 3.67,
    "renewal_date": "2025-01-31T23:59:59Z"
  },
  "batch_jobs": 12,
  "total_credits": 4200
}
GET/api/v2/usage/details

Get individual usage event records with pagination for the authenticated tenant. Supports filtering by date range, API key, and operation type. Requires VIEW permission. Rate limit: 30/min.

Request

// Query parameters:
?start_date=2025-01-01T00:00:00Z   // optional - Start date for usage period
&end_date=2025-01-31T23:59:59Z     // optional - End date for usage period
&api_key_id=uuid                    // optional - Filter by specific API key
&operation_type=describe             // optional - Filter by operation type
&page=1                              // optional - Page number (default: 1, min: 1)
&page_size=50                        // optional - Items per page (default: 50, min: 1, max: 100)

Response

{
  "events": [
    {
      "id": "evt_abc123",
      "timestamp": "2025-01-15T14:30:00Z",
      "operation_type": "describe",
      "operation_subtype": "standard",
      "endpoint": "/api/v2/describe",
      "method": "POST",
      "status_code": 200,
      "response_time_ms": 312,
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "error_code": null,
      "api_key_id": "key_xyz789"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 3665,
    "total_pages": 74
  }
}
GET/api/v2/usage/by-period

Get usage data grouped by time period for charts and analytics. Returns time-series data points. Requires VIEW permission. Rate limit: 30/min.

Request

// Query parameters:
?period_type=day                     // optional - Period grouping: hour, day, month (default: day)
&start_date=2025-01-01T00:00:00Z    // optional - Start date
&end_date=2025-01-31T23:59:59Z      // optional - End date
&api_key_id=uuid                     // optional - Filter by API key

Response

{
  "period_type": "day",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-01-31T23:59:59Z",
  "data": [
    {
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 125,
      "label": "2025-01-01"
    },
    {
      "timestamp": "2025-01-02T00:00:00Z",
      "value": 143,
      "label": "2025-01-02"
    }
  ]
}
GET/api/v2/usage/top-endpoints

Get the most frequently used endpoints ranked by request count. Useful for understanding API usage patterns. Requires VIEW permission. Rate limit: 30/min.

Request

// Query parameters:
?limit=10                            // optional - Number of top endpoints (default: 10, min: 1, max: 50)
&start_date=2025-01-01T00:00:00Z    // optional - Start date
&end_date=2025-01-31T23:59:59Z      // optional - End date

Response

{
  "endpoints": [
    {
      "endpoint": "/api/v2/describe",
      "operation_type": "describe",
      "request_count": 3500,
      "avg_response_time_ms": 280.3
    },
    {
      "endpoint": "/api/v2/verify",
      "operation_type": "verify",
      "request_count": 120,
      "avg_response_time_ms": 195.7
    }
  ]
}

Credit Usage

POST/api/v2/usage/check

Check whether an operation would exceed usage limits before attempting it. Allows pre-flight validation of credit availability. Rate limit: 60/min.

Request

{
  "verification_level": "standard",  // optional - Level: quick, standard, thorough, critical (default: "standard")
  "item_count": 1                    // optional - Number of items to process (default: 1)
}

Response

{
  "can_proceed": true,
  "current_usage": 3665,
  "monthly_limit": 100000,
  "required_credits": 2,
  "available_credits": 96335,
  "reset_date": "2025-02-01",
  "message": null
}


// When limit exceeded:
{
  "can_proceed": false,
  "current_usage": 99999,
  "monthly_limit": 100000,
  "required_credits": 2,
  "available_credits": 1,
  "reset_date": "2025-02-01",
  "message": "Operation requires 2 credits, but only 1 available"
}
GET/api/v2/usage/breakdown

Get a detailed breakdown of credit usage by verification level and operation type for the current month. Shows how credits are consumed across quick, standard, thorough, and critical levels, as well as describe, verify, and batch operations. Rate limit: 30/min.

Response

{
  "current_month": "2025-01",
  "total_credits_used": 4200,
  "monthly_limit": 100000,
  "remaining_credits": 95800,
  "usage_percentage": 4.2,
  "by_verification_level": {
    "quick": 500,
    "standard": 2400,
    "thorough": 800,
    "critical": 500
  },
  "by_operation_type": {
    "describe": 3000,
    "verify": 600,
    "batch_describe": 500,
    "batch_verify": 100
  },
  "recent_operations": [
    {
      "timestamp": "2025-01-15T14:30:00Z",
      "operation": "describe",
      "verification_level": "standard",
      "credits": 2,
      "endpoint": "/api/v2/describe",
      "status_code": 200
    }
  ],
  "reset_date": "2025-02-01T00:00:00+00:00"
}
GET/api/v2/usage/plan

Get comprehensive plan utilization and subscription information including billing period, feature limits, usage projections, and optimization recommendations. Requires VIEW permission. Rate limit: 30/min.

Request

// Query parameters:
?period=month                        // optional - Billing period: month, quarter, year (default: month)
&include_projections=true            // optional - Include usage projections and recommendations (default: true)

Response

{
  "billing_period": {
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-01-31T23:59:59Z",
    "days_in_period": 31,
    "days_remaining": 16,
    "renewal_date": "2025-02-01T00:00:00Z"
  },
  "plan_details": {
    "plan_name": "Professional",
    "monthly_requests_limit": 100000,
    "requests_used": 3665,
    "requests_remaining": 96335,
    "usage_percentage": 3.67,
    "features": {
      "verification_levels": ["quick", "standard", "thorough", "critical"],
      "rule_sets_limit": 50,
      "rule_sets_used": 12,
      "batch_processing": true,
      "priority_support": true
    }
  },
  "current_usage": {
    "total_requests": 3665,
    "by_service": {
      "describe": {
        "requests": 3500,
        "percentage": 95.5
      },
      "verify": {
        "requests": 120,
        "percentage": 3.3
      }
    },
    "by_verification_level": {
      "standard": {
        "requests": 2800,
        "percentage": 76.4
      },
      "thorough": {
        "requests": 500,
        "percentage": 13.6
      }
    }
  },
  "projections": {
    "projected_monthly_requests": 7500,
    "daily_average_requests": 244,
    "trending": "stable",
    "will_exceed_limit": false,
    "projected_usage_percentage": 7.5
  },
  "optimization_recommendations": {
    "suggestions": [
      {
        "type": "verification_level",
        "message": "Consider using 'quick' verification for non-critical items to save credits",
        "potential_request_savings": 500
      }
    ],
    "upgrade_recommendation": {
      "suggested": false,
      "reason": "Current usage is well within plan limits",
      "next_plan": "Enterprise",
      "benefits": ["Unlimited requests", "Dedicated support"]
    }
  }
}

Token Usage

GET/api/v2/usage/tokens/monthly

Get monthly token usage broken down by operation type (describe, chat, verify) including cache token metrics. Returns zero values if no data exists for the specified month. Rate limit: 30/min.

Request

// Query parameters:
?year=2025                           // optional - Year to query (defaults to current year)
&month=1                             // optional - Month to query, 1-12 (defaults to current month)

Response

{
  "year": 2025,
  "month": 1,
  "describe_input_tokens": 125000,
  "describe_output_tokens": 45000,
  "describe_operations": 3500,
  "chat_input_tokens": 85000,
  "chat_output_tokens": 32000,
  "chat_messages": 420,
  "verify_input_tokens": 18000,
  "verify_output_tokens": 6500,
  "verify_operations": 120,
  "describe_cache_read_tokens": 50000,
  "describe_cache_creation_tokens": 12000,
  "chat_cache_read_tokens": 30000,
  "chat_cache_creation_tokens": 8000,
  "verify_cache_read_tokens": 5000,
  "verify_cache_creation_tokens": 2000,
  "total_input_tokens": 228000,
  "total_output_tokens": 83500,
  "total_tokens": 311500,
  "total_cache_read_tokens": 85000,
  "total_cache_creation_tokens": 22000
}
GET/api/v2/usage/tokens/files

Get per-file token usage for processed files. Returns token counts for each file that has been processed with auto-describe, sorted by most recent first. Rate limit: 30/min.

Request

// Query parameters:
?limit=50                            // optional - Maximum files to return (default: 50, min: 1, max: 100)
&offset=0                            // optional - Offset for pagination (default: 0, min: 0)

Response

{
  "files": [
    {
      "image_id": "img_abc123",
      "filename": "product-photo.jpg",
      "input_tokens": 1200,
      "output_tokens": 450,
      "total_tokens": 1650,
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "created_at": "2025-01-15T14:30:00Z"
    }
  ],
  "total_count": 3500,
  "total_input_tokens": 125000,
  "total_output_tokens": 45000
}
GET/api/v2/usage/tokens/conversations

Get per-conversation token usage aggregated by chat session. Only includes sessions with token usage, sorted by most recent first. Rate limit: 30/min.

Request

// Query parameters:
?limit=50                            // optional - Maximum conversations to return (default: 50, min: 1, max: 100)
&offset=0                            // optional - Offset for pagination (default: 0, min: 0)

Response

{
  "conversations": [
    {
      "session_id": "sess_abc123",
      "title": "Product Analysis Discussion",
      "input_tokens": 5200,
      "output_tokens": 3100,
      "total_tokens": 8300,
      "message_count": 12,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total_count": 420,
  "total_input_tokens": 85000,
  "total_output_tokens": 32000
}

Related

Rate Limits

API rate limiting details