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