La API de Clay y sus integraciones: qué entra, qué sale y qué se monta a mano

Lo esencial Clay tiene una API pública: https://api.clay.com/public/v0, una cabecera clay-api-key, 13 operaciones documentadas y una especificación OpenAPI 3.1.0 de 67.151 bytes que el 29 de agosto de 2026 se podía descargar en developers.clay.com/openapi.json. Hay otras cinco cosas a las que se llama «la API de Clay» y no lo son: la columna HTTP, un webhook de entrada usado como fuente, un webhook de salida firmado, la acción nativa de un proveedor y el servidor MCP. Cada una exige su propio plan y tiene su propio tope. Cuando Clay documenta un comportamiento pero no publica la cifra, aquí lo digo.

El mes pasado, un responsable de RevOps me pasó un artículo como prueba de que Clay no tenía API. Todavía hay muchos textos que lo repiten. Describen un producto que ya ha cambiado: la URL base es pública y la especificación se descarga sin dar guerra. La bajé el 29 de agosto: 67.151 bytes, OpenAPI 3.1.0, 13 operaciones.

Clay nunca le ha dedicado una entrada de su changelog a la plataforma de desarrollo, y eso explica en parte que la respuesta desfasada siga saliendo arriba en Google. Lo que viene ahora es cómo se conecta todo: qué crea filas, qué rellena celdas, hasta dónde llega tu código y todos los topes publicados.

¿Clay tiene API?

Sí. La API pública de Clay está en https://api.clay.com/public/v0, se autentica con una cabecera clay-api-key que generas en Settings → Account → API keys (una sección que sigue en beta) y expone 13 operaciones: una comprobación de identidad, ejecuciones de routines, trabajos por lotes, Searches y consultas a tablas. Si la clave se rechaza, la respuesta es {"message": "Authentication failed"}. Las claves se usan solo del lado del servidor.

La especificación es legible por máquina, de modo que el cliente se puede generar automáticamente: openapi.json declara info.title «Clay Public API», info.version «0» y un único esquema ClayApiKey. No hay openapi.yaml.

Integraciones de Clay: diez vías y cómo saber cuál necesitas

Las filas entran por una fuente o no entran: la API pública lee tablas, pero nunca las crea.

La mayoría de los tickets que dicen «necesitamos la API de Clay» piden en realidad una fuente o una columna. Saber cuál de las dos es marca la diferencia entre un sprint y un cambio de plan.

Antes de planificar nada en torno a ese último bloque, conviene tener presente una contradicción. university.clay.com/docs/clay-api-cli dice que la plataforma de desarrollo está «disponible en todos los planes de Clay, incluidos los gratuitos y los de prueba», y que las llamadas por API y por CLI consumen «los mismos créditos y acciones que el trabajo equivalente hecho dentro del producto». El FAQ de precios, en cambio, incluye «acceso a la API de Clay» entre lo que trae el plan Enterprise, y la tabla comparativa no tiene ninguna fila de API. Compruébalo primero en tu propio workspace. El mismo documento aporta otros dos detalles: la CLI y la API funcionan en Mac y en Linux en beta abierta, pero no en Windows, y la beta del Agent Plugin está disponible en los planes actuales y en los antiguos hasta finales de 2026.

Launch cuesta 185 $ al mes, o 167 $ con facturación anual; Growth, 495 $ y 446 $. Clay publica sus precios en dólares y aquí se quedan así, sin convertir; todos los tramos están en los precios de Clay. Para su directorio de proveedores, Clay da tres cifras distintas: «más de 200 proveedores» en el menú de navegación, «más de 150 socios de datos» en el FAQ de precios y, según mi recuento de clay.com/integrations del 29 de agosto, 157 URL únicas de /integrations/data-provider/ repartidas en 24 categorías.

Routines: la unidad de trabajo a la que tu código puede llamar

Una routine es lógica de Clay con identificador propio: montas una función personalizada en la interfaz, activas su integración por API, coges el id t_... y le pones delante function:.

Los trabajos pequeños se lanzan en una sola llamada. POST /routines/{routine_id}/run acepta un array items de mínimo 1 y máximo 100; Clay titula esa página de referencia «Execute a routine against 1-100 items», o sea que el tope está en el propio titular. Responde 202 con un routine_run_id y admite un webhook_id opcional.

Los trabajos grandes necesitan cuatro llamadas: pides una URL prefirmada a run-batch/upload-url, subes el JSONL con un PUT como application/x-ndjson con líneas del tipo {"id": "row-1", "inputs": {"domain": "clay.com"}}, lanzas un POST a run-batch/start y recoges el resultado con un GET /routines/run-batch/{id}/results. La CLI mete las cuatro en una sola orden, clay routines runs start function:t_abc123 --bulk rows.jsonl, y clay login --device te autentica en una máquina sin pantalla.

Searches consulta la base GTM propia de Clay, con búsqueda avanzada (en beta, con booleanos anidados) o con filtros estructurados, dentro de los topes de la tabla de límites de más abajo. Si te pasas de uno, Clay responde con un HTTP 402 y te dice cuál. Una advertencia: university.clay.com/docs/clay-api-cli habla de 10.000 resultados por petición en los planes de pago de autoservicio, mientras que developers.clay.com/searches dice 500. Aquí cito la documentación para desarrolladores.

Queda un límite que no menciona ninguno de los resultados de la primera página de Google. Clay dice que «no hay planes, por ahora, de permitir la creación de tablas desde la plataforma de desarrollo». Tables es de solo lectura, solo existe en Enterprise y se consulta en POST /public/v0/tables/query; no hay ningún endpoint que liste las tablas. Las filas entran por una fuente o no entran: en qué orden montar esa parte lo explico en cómo usar Clay.

Qué te dice Clay cuando una llamada falla

Clay documenta a fondo cómo se comporta cuando algo falla, pero no publica ninguna cifra sobre dónde salta el límite de peticiones. Aclara ese punto antes de dimensionar un trabajo.

Cuando superas el límite de peticiones por workspace, recibes un HTTP 429, un Retry-After en segundos y las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset «cuando están disponibles». La CLI lo señala con el código de salida 4. El consejo de Clay es tratar el 429 como un error que admite reintento y «preferir los endpoints por lotes y asíncronos antes que los bucles de sondeo continuo».

Las respuestas de error (todo lo que no es 2xx) llegan en JSON con un message legible. Clay avisa de que «los cuerpos de respuesta de error no incluyen, por ahora, códigos de error estables», de modo que tu switch tiene que basarse en el código de estado: 401 y 403, autenticación; 404, recurso inexistente; 409 y 422, validación; 429, exceso de peticiones; 5xx, fallo pasajero. Un 202 en un endpoint asíncrono no significa que haya salido bien. Significa que sigue en marcha.

La columna HTTP API: conectar una fuente de la que Clay no ha oído hablar

Esta columna conecta Clay con algo que no está en su directorio: «te permite enviar o recuperar datos de cualquier herramienta o base de datos usando un endpoint de API, aunque Clay no ofrezca una integración nativa», con GET, POST, PUT y DELETE. Fíjate en un detalle: todos los códigos de estado que Clay documenta aquí describen lo que pasa en el endpoint al que has llamado, no en Clay. Ahí es donde hay que mirar cuando una columna se pone roja.

La última fila le da la vuelta a la lógica habitual: ese límite lo pones tú, no te lo impone Clay. Se hace con dos campos, Request limit y Duration (ms), y el ejemplo del propio Clay, 10 sobre 1.000 ms, equivale a diez peticiones por segundo.

Dos avisos sobre credenciales, los dos de Clay. Una clave escrita a mano en el campo Headers queda «visible en texto plano para cualquiera que tenga acceso a la columna de la tabla», con lo cual más vale usar una cuenta guardada. La pega es que editar una de esas cuentas «afectará a todas las columnas de enriquecimiento HTTP API de tu workspace que la usen».

Los webhooks de Clay van en dos sentidos y no comparten más que el nombre

Vaciar la tabla no recupera ninguno de los 50.000 envíos, y un webhook de salida puede no llegar nunca.

El de entrada es una fuente: pulsas + Add abajo del todo en un workbook, buscas Webhooks, eliges Monitor webhook y copias la URL. El token de autenticación se ve una vez y solo una: «asegúrate de copiar el token inmediatamente, porque a los tokens de autenticación solo se puede acceder una vez». Después llega el tope que pilla desprevenidos a muchos equipos: una fuente webhook admite 50.000 envíos, y ese contador «se mantiene incluso después de borrar filas». Vaciar la tabla no sirve de nada; por debajo de Enterprise te toca crear otra fuente. La guía lleva la etiqueta de un plan «Explorer» que ya no aparece en la página de precios, así que confirma el nivel en tu propio workspace.

El de salida pertenece a la plataforma de desarrollo. clay webhooks create https://example.com/hooks/clay devuelve un id, una url, un createdAt y un signingSecret que conviene «guardar de inmediato, porque no se puede recuperar después». Los payloads llevan webhookId, createdAt y un objeto data, y van firmados con X-Clay-Signature: sha256= seguido de un HMAC-SHA256 calculado sobre el cuerpo. Y luego está la frase que debería condicionar tu arquitectura, no tu gestor de errores: «La entrega de los webhooks no está garantizada. Usa los webhooks para reaccionar más rápido, pero sigue consultando los resultados de la ejecución como plan B».

Clay y LinkedIn: los límites de Find People y qué hace de verdad la extensión de Chrome

Find People es donde suelen empezar las listas de tipo LinkedIn, con los topes que recoge la tabla de más abajo y un límite de exclusiones: 300.000 personas y 100.000 por fuente, repartidas en tres conjuntos y cruzadas por URL de LinkedIn. La documentación de Clay no dice en ningún momento de dónde salen esos datos, así que yo tampoco lo voy a decir.

La extensión de Chrome es lo que más confunde a quien llega buscando información, así que lo digo sin rodeos: la documentación de Clay describe sus dos extensiones como herramientas de extracción, no como herramientas para obtener contactos. Clay for Chrome saca datos estructurados de una página y vuelca en una tabla campos como el nombre, la web, LinkedIn o Crunchbase. Clip to Clay guarda páginas enteras. En la tienda de Chrome, la ficha de Clay for Chrome muestra una nota de 4,4 sobre 5 con 9 valoraciones, 10.000 usuarios, la versión 1.0.0 y una última actualización del 10 de abril de 2025.

Clay MCP: tu workspace dentro de un asistente

El servidor MCP de Clay conecta un workspace con Claude, ChatGPT, Microsoft Copilot y Glean, y se administra en Settings → MCP users. Los controles de créditos están disponibles en Launch, Growth y Enterprise; los de audiencia, solo en Enterprise. La facturación es exactamente la misma que dentro del producto: «Si una función que encuentra el email y el teléfono de una persona cuesta 12 créditos en una tabla de Clay, cuesta 12 créditos cuando un comercial la lanza desde Claude o ChatGPT». El agent plugin es otra cosa: la documentación para desarrolladores lo describe como el paquete que lleva las habilidades de Clay y la CLI clay a agentes de programación como Claude Code, Codex o Cursor. O sea que se usa desde un terminal, no desde un cliente de chat.

Todos los topes que Clay pone por escrito

Casi todos los límites de Clay están en 50.000, y el de la fuente webhook es el que hay que tener en cuenta al diseñar, porque su contador no se reinicia aunque borres filas.

El enriquecimiento masivo por encima de 50.000 registros es solo de Enterprise. Y hay una línea de la documentación de fuentes que conviene leer antes de una importación grande: al llegar al límite de filas, «Clay importa registros hasta el límite y se para automáticamente. No se muestra ningún mensaje de error». Las soluciones que propone el propio Clay son partir el archivo por filtro o por rango de fechas, o pasarse a las tablas de autoborrado y al enriquecimiento masivo de Enterprise.

Añadir Enrow como columna en tu tabla

Ni Clay ni Enrow cobran una búsqueda vacía: una cadena que reintenta solo paga cuando hay resultado.

Enrow está en el directorio de Clay desde el 1 de septiembre de 2024, en las categorías Contact Data y Contact Data Verification, con una integración desarrollada por el propio Clay y etiquetada como «Included in All Plans». Tres acciones funcionan como columnas, y cada una devuelve un estado de cualificación junto al resultado.

Nuestra propia documentación registra un coste en créditos de Clay para esa verificación, mientras que la ficha de Clay la da por gratuita: confírmalo dentro de la aplicación. Con tu propia clave, apunta una columna HTTP API a https://api.enrow.io/email/find/single, con las cabeceras x-api-key y Content-Type: application/json, y el cuerpo {"company_domain": /company_domain, "fullname": "/first_name /last_name"}. La respuesta es asíncrona, así que pásale una URL de webhook de Clay en settings.webhook, o consulta el id de búsqueda en el GET correspondiente hasta que devuelva algo. Pon Request limit a 10 y Duration a 1000 para que cuadre: cada endpoint POST de Enrow admite diez peticiones por segundo y por clave, y un POST por lotes cuenta como una sola petición aunque lleve dentro 5.000 emails.

Ahora, lo que más importa cuando tu cadena reintenta peticiones. La regla de Clay: «si un enriquecimiento no devuelve resultado, no se te cobran Data Credits ni Actions». La de Enrow dice lo mismo desde el lado del proveedor: solo se te descuenta un crédito cuando hay un resultado verificado, nunca por un fallo. Cuando sí hay resultado, un email cuesta 1 crédito de Enrow, un móvil 40 y una verificación un cuarto, todo de la misma bolsa de créditos. El orden de las fuentes lo vemos en las cascadas de enriquecimiento de Clay.

Enrow somete cada dirección a más de 10 verificaciones antes de darla por buena, resuelve los dominios catch-all y entrega la dirección en vez de marcarla como dudosa. En nuestros propios ficheros la tasa de acierto ronda el 60 % y la tasa de bounce se queda por debajo del 1 %: son mediciones nuestras, nunca cifras que prometamos.

La lista que Enrow no te va a montar

Enrow encuentra los datos de personas que tú ya has identificado. Para un email hacen falta un nombre completo y un dominio; para un móvil, una URL de perfil o un nombre con el contexto de la empresa. Detrás no hay ninguna base de datos que puedas consultar, de manera que «todos los VP de Ingeniería de Ámsterdam en empresas de Serie B» te devuelve una lista vacía. Es a propósito. Las direcciones almacenadas envejecen sin avisar y una búsqueda en tiempo real no, y prefiero quedarme sin función de búsqueda antes que ofrecer una con datos caducados. Dentro de Clay eso no te cuesta nada, porque Find People, una sincronización con el CRM o un CSV ya se encargan de ese paso antes. Los criterios para elegir están en cómo elegir un proveedor de datos B2B.

Si lo que tienes montado es código y no un workbook, puedes lanzar esas mismas consultas directamente. La API de Enrow te da una clave sin hablar con ningún comercial, y ya hay SDK oficiales en siete lenguajes (JS/TypeScript, Python, PHP, Go, Java, Swift y Rust), todos en acceso anticipado y con el código fuente en GitHub. El servidor MCP EnrowAPI/enrow-mcp pone esas tres consultas al alcance de un asistente, para que Claude o Cursor resuelvan un contacto sin ninguna tabla de por medio. El detalle de los endpoints está en la API de búsqueda de emails.

FAQ

¿La API de Clay es gratis?

La plataforma de desarrollo no lleva ningún recargo. La documentación de Clay dice que está disponible en todos los planes, incluidos el gratuito y los de prueba, y que las llamadas por API y por CLI consumen los mismos créditos y acciones que el trabajo equivalente hecho dentro del producto. Lo que de verdad te limita son las 500 acciones y los 100 créditos de datos al mes del plan Free.

¿Qué diferencia hay entre la HTTP API de Clay y la API pública de Clay?

Funcionan en sentidos opuestos. La HTTP API es una columna dentro de una tabla de Clay que llama a un endpoint de terceros y escribe la respuesta en una fila; la tabla comparativa de Clay la reserva al plan Growth. La API pública, en https://api.clay.com/public/v0, es a la que llama tu propio código desde fuera de Clay, para ejecutar routines, lanzar trabajos por lotes y consultar Searches.

¿Qué plan necesito para la HTTP API y los webhooks de Clay?

Growth. La tabla comparativa de Clay marca «HTTP API integrations» y «Automate any signal via webhooks» como no incluidas en Free ni en Launch, y deja las conexiones con el CRM y con el data warehouse en ese mismo nivel. La API pública, la CLI y el servidor MCP funcionan en todos los planes según la documentación para desarrolladores.

¿Qué límites de peticiones tiene la API de Clay?

Clay publica el comportamiento y no la cifra. La API pública aplica un límite de peticiones por workspace, responde con un HTTP 429, manda un Retry-After en segundos y añade las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset cuando están disponibles. En la documentación no aparece ninguna cifra de peticiones por segundo.

¿Puedo escribir datos en una tabla de Clay con la API?

No. Clay dice que, por ahora, no hay planes de permitir la creación de tablas desde la plataforma de desarrollo. Tables es de solo lectura y solo de Enterprise, y se consulta en POST /public/v0/tables/query con un tamaño de página máximo de 100 filas. Las filas entran por una fuente.

¿Hay un límite de webhooks en Clay?

Sí, y es permanente. Una fuente webhook de Clay admite 50.000 envíos, y Clay documenta que ese límite «se mantiene incluso después de borrar filas», de manera que vaciar la tabla no reinicia nada. Por debajo de Enterprise la solución es crear otra fuente; Enterprise levanta el tope con las tablas de autoborrado.

¿Qué hace la extensión de Chrome de Clay?

La extensión de Chrome de Clay hace scraping de páginas, no busca datos de contacto. Clay for Chrome extrae datos estructurados de una página web, de una lista autodetectada o de un perfil individual, y los mete en una tabla de Clay mapeando campos como el nombre, la web, LinkedIn, Twitter o Crunchbase. Clip to Clay, la segunda extensión, guarda páginas web enteras en una tabla.

¿Clay tiene servidor MCP?

Sí, y conecta un workspace con Claude, ChatGPT, Microsoft Copilot y Glean. Se gestiona en Settings → MCP users, con controles de créditos a partir de Launch y un gasto que se reinicia el día 1 de cada mes a medianoche UTC. Clay no cobra ningún extra por MCP: 12 créditos en una tabla son 12 créditos desde un asistente.

Abre tu workspace, apunta lo que de verdad ejecutas y coloca cada cosa en una fila de la primera tabla. La respuesta a «¿esto se puede automatizar?» suele estar ya en la cuenta, un nivel de plan más arriba o una columna más allá.

Si lo que te falta es un email verificado o un móvil europeo, Enrow está en ese directorio como una columna que puedes activar hoy mismo. El plan gratuito te da 50 créditos nuevos a principios de cada mes, durante el tiempo que quieras y sin pedirte tarjeta, para la aplicación, la extensión de Chrome y los asistentes de IA. Conectar tu propia clave de Enrow a la columna pasa por la API, que se abre con cualquier compra: un plan desde 15 €/mes o un paquete de créditos sin suscripción.