Skip to content

Usage Statistics API

Overview

The Usage Statistics API (/v1/usage) provides comprehensive usage statistics and billing information for your Wickson API account. This endpoint allows you to track your API consumption, monitor storage usage, understand billing details, and review recent transactions.

Endpoint

GET https://api.wickson.ai/v1/usage

Request

Headers

  • X-Api-Key: Required. Your Wickson API key

Query Parameters

  • start_time: Optional. The start of the time range for usage statistics (ISO 8601 format, e.g., 2024-12-12T00:00:00Z). Defaults to 7 days ago.
  • end_time: Optional. The end of the time range for usage statistics (ISO 8601 format). Defaults to the current time.
  • group_by: Optional. The time unit for grouping usage data. Possible values: day (default), hour, month.
  • detailed: Optional. Include detailed usage metrics and recent transactions. Possible values: true, false (default).

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" "https://api.wickson.ai/v1/usage?start_time=2024-12-12T00:00:00Z&end_time=2024-12-19T12:00:00Z&detailed=true"

Python Example

import requests
from datetime import datetime, timedelta

# Configuration
api_key = "YOUR_API_KEY"

# Set time range (last 7 days)
end_time = datetime.utcnow()
start_time = end_time - timedelta(days=7)

# Request usage statistics
response = requests.get(
    "https://api.wickson.ai/v1/usage",
    headers={"X-Api-Key": api_key},
    params={
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
        "group_by": "day",
        "detailed": True
    }
)

# Process response
if response.status_code == 200:
    data = response.json()["data"]

    # Print account information
    account = data["account_info"]
    print(f"Account: {account['user_id']} ({account['tier']} tier)")
    print(f"Balance: ${account['balance']:.2f}")
    print(f"Status: {account['payment_status']}")

    # Print billing summary
    billing = data["billing_summary"]
    print(f"\nCurrent Balance: ${billing['current_balance']:.2f}")

    # Print usage costs
    print("\nUsage Costs:")
    for operation, cost in billing["usage_costs"].items():
        print(f"- {operation}: ${float(cost):.2f}")

    # Print storage usage
    if "storage_usage" in data:
        storage = data["storage_usage"]["total"]
        print(f"\nStorage: {storage['vectors']} vectors ({storage['size_gb']:.2f} GB)")
        print(f"Quota: {storage['quota_used_percent']}% used of {storage['quota_limit']} vectors")

    # Print detailed metrics if available
    if "detailed_metrics" in data:
        detailed = data["detailed_metrics"]

        # Print usage trends
        if "usage_trends" in detailed:
            print("\nUsage Trends:")
            for operation, dates in detailed["usage_trends"].items():
                print(f"- {operation}:")
                for date, cost in dates.items():
                    print(f"  {date}: ${float(cost):.2f}")

        # Print recent transactions
        if "recent_transactions" in detailed:
            print("\nRecent Transactions:")
            for tx in detailed["recent_transactions"][:5]:  # Show first 5 transactions
                print(f"- {tx['timestamp']} | {tx['type']} | ${float(tx['amount']):.2f} | {tx['status']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Usage statistics retrieved successfully",
  "data": {
    "account_info": {
      "balance": 10.00,
      "tier": "standard",
      "last_billing_date": "2024-12-12T00:00:00Z",
      "payment_status": "active",
      "user_id": "user-123"
    },
    "billing_summary": {
      "current_balance": 10.00,
      "usage_costs": {
        "document_processing": 0.30,
        "basic_search": 0.10
      },
      "pricing": {
        "DOCUMENT_PROCESSING": 0.03,
        "BASIC_SEARCH": 0.00,
        "ADVANCED_SEARCH": 0.01,
        "VECTOR_PROCESSING": 0.00,
        "RAG_QUERY": 0.03,
        "MEDIA_ANALYSIS": 0.03,
        "LLM_QUERY_": 0.01
      }
    },
    "storage_usage": {
      "total": {
        "vectors": 1500,
        "size_gb": 4.53,
        "quota_limit": 10000,
        "quota_used_percent": 15.00
      }
    }
  },
  "metadata": {
    "time_range": {
      "start": "2024-12-12T12:00:00Z",
      "end": "2024-12-19T12:00:00Z",
      "group_by": "day"
    },
    "api_version": "1.0.0",
    "detailed": false,
    "cache_ttl": 300
  }
}

Detailed Metrics (when detailed=true)

When you include detailed=true in your request, the response will include additional metrics:

"detailed_metrics": {
  "usage_trends": {
    "document_processing": {
      "2024-12-18": 0.15,
      "2024-12-19": 0.15
    },
    "basic_search": {
      "2024-12-19": 0.10
    }
  },
  "recent_transactions": [
    {
      "timestamp": "2024-12-19T11:55:00Z",
      "type": "document_processing",
      "amount": 0.03,
      "status": "completed"
    },
    {
      "timestamp": "2024-12-19T10:30:00Z",
      "type": "basic_search",
      "amount": 0.00,
      "status": "completed"
    }
  ]
}

Error Responses

Invalid Datetime Format (400 Bad Request)

{
  "success": false,
  "message": "Invalid datetime format",
  "code": "validation_error",
  "status_code": 400,
  "details": {
    "format": "ISO format (YYYY-MM-DDTHH:MM:SS)",
    "error": "Invalid isoformat string: '2024-13-01'"
  }
}

User Not Found (404 Not Found)

{
  "success": false,
  "message": "User account not found",
  "code": "resource_not_found",
  "status_code": 404,
  "details": {
    "resource_type": "user_account",
    "resource_id": "user-123"
  }
}

Internal Server Error (500 Internal Server Error)

{
  "success": false,
  "message": "Failed to retrieve usage statistics",
  "code": "processing_error",
  "status_code": 500,
  "details": {
    "error": "Database connection error"
  }
}

Response Details

Account Information

Field Description
account_info.balance Current account balance in USD
account_info.tier Account tier (e.g., standard, pro)
account_info.last_billing_date Date of last billing event
account_info.payment_status Status of your account (active, suspended)
account_info.user_id Your user identifier

Billing Summary

Field Description
billing_summary.current_balance Current account balance in USD
billing_summary.usage_costs Costs incurred by operation type
billing_summary.pricing Current pricing for all operation types

Storage Usage

Field Description
storage_usage.total.vectors Total number of vectors stored
storage_usage.total.size_gb Total storage size in gigabytes
storage_usage.total.quota_limit Maximum number of vectors allowed
storage_usage.total.quota_used_percent Percentage of quota used

Rate Limiting

This endpoint is subject to standard rate limiting as described in the Rate Limiting section of the API documentation. If you exceed your rate limit, you will receive a 429 Too Many Requests response.

Notes

  • Usage data may have a slight delay (typically less than 5 minutes) as aggregation occurs periodically.
  • For very large accounts with extensive usage history, consider using narrower time ranges to improve response times.
This site uses cookies to help us improve the overall documentation and browsing experience. By continuing to use this site, you agree to our Privacy Policy.