clay-rate-limits

name	clay-rate-limits
description	Handle Clay rate limits, webhook throttling, and credit pacing strategies. Use when hitting 429 errors, managing webhook submission rates, or optimizing throughput within Clay's plan limits. Trigger with phrases like "clay rate limit", "clay throttling", "clay 429", "clay slow", "clay records per hour".
allowed-tools	Read, Write, Edit, Bash(curl:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","clay","api"]

Clay Rate Limits

Overview

Clay enforces rate limits at the plan level, webhook level, and enrichment provider level. Understanding these limits prevents data loss, credit waste, and integration failures.

Prerequisites

• Clay account with known plan tier
• Webhook URL(s) for your tables
• Understanding of your data volume requirements

Instructions

Step 1: Understand Clay Rate Limit Tiers

Plan	Records/Hour	Webhook Limit	HTTP API Columns	Enterprise API
Free	Limited	50K lifetime per webhook	Not available	Not available
Starter	Standard	50K lifetime per webhook	Not available	Not available
Explorer	400/hour	50K lifetime per webhook	Not available	Not available
Pro	Unlimited	50K lifetime per webhook	Available	Not available
Enterprise	Unlimited	50K lifetime per webhook	Available	Available

Key insight: The 50K webhook submission limit is per-webhook, not per-table. Once exhausted, create a new webhook on the same table.

Step 2: Implement Webhook Rate Limiting

// src/clay/rate-limiter.ts — respect Clay's plan-level rate limits
import PQueue from 'p-queue';

interface RateLimiterConfig {
  maxPerHour: number;     // Plan limit (e.g., 400 for Explorer)
  maxPerSecond: number;   // Practical burst limit
  webhookLimit: number;   // 50K per webhook lifetime
}

const PLAN_LIMITS: <, > = {
  : { : , : , :  },
  :      { : , : , :  },
  : { : , : , :  },
};

  {
   : ;
   submissionCount = ;
   hourlyCount = ;
   : ;
   : ;

  () {
    . = [plan];
    . =  ({
      : ,
      : ,
      : ..,
    });
    . =  (.() + );
  }

   (: , : <, >): <> {
    
     (. >= ..) {
        (
        
      );
    }

    
     (.() > ..()) {
      . = ;
      . =  (.() + );
    }
     (. >= ..) {
       waitMs = ..() - .();
      .();
        ( (r, waitMs));
      . = ;
    }

     ..( () => {
       res =  (webhookUrl, {
        : ,
        : { :  },
        : .(data),
      });

       (res. === ) {
         retryAfter = (res..() || );
        .();
          ( (r, retryAfter * ));
         .(webhookUrl, data); 
      }

      .++;
      .++;
       res;
    });
  }

  () {
     {
      : .,
      : .. - .,
      : .. - .,
    };
  }
}