Skip to main content
GET
/
kyc
/
usage
Usage Metrics
curl --request GET \
  --url https://api.example.com/kyc/usage
Retrieve usage metrics and statistics for KYC operations. Track checks, validations, errors, and watchlist activity over time.

​
Endpoint

GET /kyc/usage

​
Authentication

Requires usage:read permission. Include your Bearer token in the Authorization header.

​
Query Parameters

​
Granularity Options

GranularityDescriptionDefault Period
hour24 hourly data points for a specific dayRequires date parameter
dayDaily data points for a specific monthDefault, up to 30 days
monthMonthly data points for up to 12 monthsDefault: 1 month

​
Request Example

curl "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=day" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Additional Request Examples

​
Daily Granularity (Specific Month)

curl "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=day&year_month=2024-10" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Hourly Granularity (Specific Day)

curl "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=hour&date=2024-10-27" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Monthly Granularity (Last 6 Months)

curl "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=month&months=6" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Invalidate Cache

curl "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=day&cache_bust=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response Format

​
Success Response (Daily Granularity)

{
  "tenant_id": "tenant123",
  "granularity": "day",
  "period": {
    "year_month": "2024-10"
  },
  "data": [
    {
      "timestamp": "2024-10-01",
      "metrics": {
        "check_count": 150,
        "validation_count": 145,
        "error_count": 5,
        "watchlist_scan_count": 20,
        "watchlist_invocation_count": 500
      }
    },
    {
      "timestamp": "2024-10-02",
      "metrics": {
        "check_count": 180,
        "validation_count": 175,
        "error_count": 5,
        "watchlist_scan_count": 25,
        "watchlist_invocation_count": 600
      }
    }
  ],
  "summary": {
    "total_check_count": 4500,
    "total_validation_count": 4350,
    "total_error_count": 150,
    "total_watchlist_scan_count": 600,
    "total_watchlist_invocation_count": 15000
  }
}

​
Success Response (Hourly Granularity)

{
  "tenant_id": "tenant123",
  "granularity": "hour",
  "period": {
    "date": "2024-10-27"
  },
  "data": [
    {
      "timestamp": "2024-10-27T00:00:00Z",
      "metrics": {
        "check_count": 5,
        "validation_count": 5,
        "error_count": 0,
        "watchlist_scan_count": 0,
        "watchlist_invocation_count": 0
      }
    },
    {
      "timestamp": "2024-10-27T01:00:00Z",
      "metrics": {
        "check_count": 12,
        "validation_count": 12,
        "error_count": 0,
        "watchlist_scan_count": 1,
        "watchlist_invocation_count": 5
      }
    }
  ],
  "summary": {
    "total_check_count": 250,
    "total_validation_count": 245,
    "total_error_count": 5,
    "total_watchlist_scan_count": 10,
    "total_watchlist_invocation_count": 250
  }
}

​
Success Response (Monthly Granularity)

{
  "tenant_id": "tenant123",
  "granularity": "month",
  "period": {
    "months": 6
  },
  "data": [
    {
      "timestamp": "2024-05",
      "metrics": {
        "check_count": 12000,
        "validation_count": 11800,
        "error_count": 200,
        "watchlist_scan_count": 1500,
        "watchlist_invocation_count": 45000
      }
    },
    {
      "timestamp": "2024-06",
      "metrics": {
        "check_count": 15000,
        "validation_count": 14700,
        "error_count": 300,
        "watchlist_scan_count": 1800,
        "watchlist_invocation_count": 54000
      }
    }
  ],
  "summary": {
    "total_check_count": 90000,
    "total_validation_count": 88200,
    "total_error_count": 1800,
    "total_watchlist_scan_count": 10800,
    "total_watchlist_invocation_count": 324000
  }
}

​
Response Fields

FieldTypeDescription
tenant_idstringYour tenant identifier
granularitystringTime granularity used
periodobjectPeriod parameters (year_month, date, or months)
dataarrayArray of timestamped metric objects
summaryobjectAggregated totals across all periods

​
Metric Fields

Each data point contains:
FieldTypeDescription
check_countintegerTotal KYC checks performed
validation_countintegerSuccessful validations
error_countintegerFailed validations/errors
watchlist_scan_countintegerNumber of watchlist scans executed
watchlist_invocation_countintegerTotal watchlist invocations (subjects × lists)

​
Usage Examples

​
Python Example

import requests
from datetime import datetime

token = "YOUR_TOKEN"
base_url = "https://stg.kyc.legaltalent.ai/kyc/usage"

# Get daily metrics for current month
response = requests.get(
    f"{base_url}?granularity=day",
    headers={"Authorization": f"Bearer {token}"}
)

if response.status_code == 200:
    data = response.json()
    print(f"Total checks this month: {data['summary']['total_check_count']}")
    
    # Plot daily trends
    for day in data['data']:
        print(f"{day['timestamp']}: {day['metrics']['check_count']} checks")

​
JavaScript Example

const token = "YOUR_TOKEN";

async function getUsageMetrics() {
  const response = await fetch(
    "https://stg.kyc.legaltalent.ai/kyc/usage?granularity=day",
    {
      headers: {
        "Authorization": `Bearer ${token}`
      }
    }
  );
  
  const data = await response.json();
  
  if (response.ok) {
    // Display summary
    console.log(`Total checks: ${data.summary.total_check_count}`);
    
    // Chart data points
    const chartData = data.data.map(point => ({
      date: point.timestamp,
      checks: point.metrics.check_count,
      errors: point.metrics.error_count
    }));
    
    // Use with charting library (Chart.js, D3, etc.)
    return chartData;
  } else {
    console.error("Error:", data.error);
  }
}

​
Error Responses

​
400 Bad Request - Invalid Parameters

{
  "error": "Invalid date format. Expected YYYY-MM-DD"
}
Common validation errors:
  • Invalid date format
  • Future dates/months
  • Invalid granularity value
  • Missing required date parameter for hour granularity
  • months out of range (must be 1-12)

​
403 Forbidden - Missing Permission

{
  "error": "Permission denied: usage:read required"
}

​
403 Forbidden - Missing Tenant

{
  "error": "Unauthorized: missing tenant_id"
}

​
Status Codes

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid token
403Forbidden - Insufficient permissions
500Internal Server Error

​
Caching

  • Responses are cached for 5 minutes
  • Use cache_bust=true to force fresh data
  • Cache headers: Cache-Control: max-age=300
  • With cache_bust: Cache-Control: no-cache, no-store

​
Data Characteristics

  • Gap Filling: All periods (even with zero activity) are included for continuous charts
  • Immutability: Historical data never changes, so responses are cacheable
  • Real-time: Current day/hour data updates as requests are processed
  • Retention: Metrics are retained for at least 12 months

​
Frontend Integration Tips

The response structure is optimized for graph visualization: 
// Daily granularity - 30 data points
{
  data: [
    { timestamp: "2024-10-01", metrics: {...} },
    { timestamp: "2024-10-02", metrics: {...} },
    // ... continuous, no gaps
  ]
}

// Use with any charting library
const labels = data.data.map(d => d.timestamp);
const checks = data.data.map(d => d.metrics.check_count);
const errors = data.data.map(d => d.metrics.error_count);