clay-observability

Clay Observability

Overview

Monitor Clay data enrichment pipeline health, credit consumption velocity, and enrichment success rates. Clay's credit-based pricing model means observability must track per-enrichment costs (email lookup: ~1 credit, company enrichment: ~5 credits, waterfall enrichment: variable).

Prerequisites

• Clay Team or Enterprise plan
• API access for usage queries
• External metrics/alerting system

Instructions

Step 1: Track Credit Consumption in Real Time

set -euo pipefail
# Query current credit usage by table
curl "https://api.clay.com/v1/workspace/usage?group_by=table&period=today" \
  -H "Authorization: Bearer $CLAY_API_KEY" | \
  jq '.usage[] | {table_name, credits_used, rows_enriched, avg_credits_per_row: (.credits_used / (.rows_enriched + 0.01))}'

Step 2: Monitor Enrichment Hit Rates

// clay-enrichment-monitor.ts
async function monitorEnrichments() {
  const tables = await clayApi.listTables();
  for (const table of tables) {
    const stats = await clayApi.getTableStats(table.id);
    const hitRate = stats.rows_with_data / Math.max(stats.total_rows, 1) * 100;
    emitGauge('clay_enrichment_hit_rate_pct', hitRate, { table: table.name, enrichment: stats.enrichment_type });
    emitCounter('clay_credits_consumed', stats.credits_used, { table: table.name });

    if (hitRate < 30) {
      console.warn(`Low hit rate on ${table.name}: ${hitRate.toFixed(1)}% (check enrichment config)`);
    }
  }
}

Step 3: Set Up Credit Burn Alerts

groups:
  - name: clay
    rules:
      - alert: ClayCreditBurnHigh
        expr: rate(clay_credits_consumed[1h]) > 500  # HTTP 500 Internal Server Error
        annotations: { summary: "Clay burning >500 credits/hour (projected monthly: {{ $value * 720 }})" }  # 720: HTTP 500 Internal Server Error
      - alert: ClayLowHitRate
        expr: clay_enrichment_hit_rate_pct < 20
        for: 30m
        annotations: { summary: "Clay enrichment hit rate below 20% on {{ $labels.table }}" }
      - alert: ClayCreditBalance
        expr: clay_credits_remaining < 1000  # 1000: 1 second in ms
        annotations: { summary: "Clay credit balance below 1,000 -- refill needed" }

Step 4: Log Enrichment Results for Audit

{"ts":"2026-03-10T14:30:00Z","table":"outbound-leads","enrichment":"email_finder","rows_attempted":100,"rows_enriched":72,"credits_used":100,"hit_rate":72.0,"duration_ms":4500}  # 2026: 4500 = configured value

Step 5: Build a Credit Efficiency Dashboard

Key panels: credit consumption by table (bar chart), enrichment hit rate by provider, daily/weekly credit burn trend, credits remaining gauge, and cost-per-enriched-row (credits used / rows with actual data returned). Tables with low hit rates and high credit burn are optimization targets.

Error Handling

Issue	Cause	Solution
Credits depleting fast	Waterfall enrichment trying all providers	Limit waterfall steps or set credit cap per row
Hit rate near 0%	Bad input data (invalid emails/domains)	Clean input data before enrichment
API timeout on enrichment	Provider rate limit	Reduce table auto-enrich concurrency
Usage API returning stale data	Caching lag	Wait 5 minutes for usage data to update

Examples

Basic usage: Apply clay observability to a standard project setup with default configuration options.

Advanced scenario: Customize clay observability for production environments with multiple constraints and team-specific requirements.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale

Resources

• Official monitoring documentation
• Community best practices and patterns
• Related skills in this plugin pack