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 descargable en developers.clay.com/openapi.json el 29 de agosto de 2026. 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 pide su plan y tiene su 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 dedicó una entrada de changelog a su plataforma de desarrollo, y por ahí se explica en parte que la respuesta caducada siga posicionando. Lo que viene ahora es el cableado: 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 vive en https://api.clay.com/public/v0, se autentica con una cabecera clay-api-key que se emite en Settings → Account → API keys (todavía marcada como beta) y expone 13 operaciones: una comprobación de identidad, ejecuciones de routines, trabajos por lotes, Searches y consultas a tablas. Si la clave no vale, la respuesta es {"message": "Authentication failed"}. Las claves se quedan del lado del servidor.

La especificación la lee una máquina, de modo que el cliente te lo puedes generar tú solo: 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 te toca

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 redactados como «necesitamos la API de Clay» piden en realidad una fuente o una columna. Entre una cosa y otra va la diferencia que separa un sprint de un cambio de plan.

Antes de planificar nada alrededor de ese último bloque, hay una contradicción que conviene llevarse puesta. 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 coloca «acceso a la API de Clay» entre las líneas del plan Enterprise, y la tabla comparativa no tiene ninguna fila de API. Compruébalo primero en tu propio workspace. Del mismo documento salen otros dos apuntes: la CLI y la API funcionan en Mac y en Linux en beta abierta, en Windows no, y la beta del Agent Plugin corre sobre los planes actuales y sobre los antiguos hasta el final 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; las escalas completas están en los precios de Clay. Clay cuenta su directorio de proveedores de tres maneras 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 157 URL únicas de /integrations/data-provider/ cuando conté clay.com/integrations el 29 de agosto, 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 dirección propia: 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 van en línea. 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 son 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 devuelve 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.

Falta el límite que no menciona nadie de los que salen en 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 solo lee, solo en Enterprise, en POST /public/v0/tables/query, y no existe ningún endpoint que liste las tablas. Las filas entran por una fuente o no entran: el orden de montaje de ese lado está en cómo usar Clay.

Qué te dice Clay cuando una llamada falla

Clay documenta a fondo cómo se comporta cuando algo falla, y no publica ni una cifra de dónde está el límite de peticiones. Resuelve eso antes de dimensionar un trabajo.

Recibes un HTTP 429 contra un límite de peticiones por workspace, 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 reintentable y «preferir los endpoints por lotes y asíncronos antes que los bucles de sondeo continuo».

Los cuerpos que no son 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 va sobre el estado: 401 y 403 son autenticación, 404 es que no existe, 409 y 422 son validación, 429 es exceso de peticiones, 5xx es pasajero. Un 202 en un endpoint asíncrono no significa que haya salido bien. Significa que todavía está corriendo.

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

Esta columna apunta a algo que está fuera del 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 el endpoint al que has llamado, no a Clay. Ahí es donde hay que mirar cuando una columna se pone roja.

La última fila le da la vuelta a lo normal: 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, son 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 mejor usa 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 devuelve ninguno de los 50.000 envíos, y un webhook de salida puede no llegar nunca.

El de entrada es una fuente: + 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». Y después llega el tope que pilla a los equipos: una fuente webhook admite 50.000 envíos, y esa cuenta «se mantiene incluso después de borrar filas». Vaciar la tabla no sirve de nada; por debajo de Enterprise te toca levantar 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, firmados con X-Clay-Signature: sha256= más un HMAC-SHA256 sobre el cuerpo. Y luego está la frase que debería decidir tu arquitectura y 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 con forma de LinkedIn, bajo los topes de la tabla de más abajo, más unas exclusiones de 300.000 personas y 100.000 por fuente repartidas en tres conjuntos, que se cruzan 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.

Con la extensión de Chrome es donde más se equivoca quien llega buscando, y lo digo sin rodeos: la documentación de Clay describe sus dos extensiones como herramientas de extracción, no como herramientas que revelen contactos. Clay for Chrome saca datos estructurados de una página y mapea campos como el nombre, la web, LinkedIn o Crunchbase dentro de una tabla. Clip to Clay guarda páginas enteras. La ficha de Clay for Chrome en la tienda marca 4,4 sobre 5 con 9 valoraciones, 10.000 usuarios, versión 1.0.0, actualizada el 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 llegan con Launch, Growth y Enterprise; los de audiencia son solo de 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 distinta: 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 vive en un terminal, no en un cliente de chat.

Todos los topes que Clay pone por escrito

Casi todos los límites de Clay valen 50.000, y el de la fuente webhook es el que hay que tener en cuenta al diseñar, porque su contador sobrevive al borrado.

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». Los remedios 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.

Darle a Enrow una 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 construida por el propio Clay y etiquetada como «Included in All Plans». Tres acciones funcionan como columnas, y cada una devuelve un estado de calificación al lado del 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, o sea que 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 la parte que de verdad importa en una cadena que reintenta. 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, nunca por un bounce. 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.

Detrás de cada dirección hay más de 10 verificaciones antes de darla por buena, dominios catch-all resueltos y entregados en vez de marcados como dudosos, y móviles europeos con su base legal RGPD documentada. En nuestros propios ficheros la tasa de acierto ronda el 60 % y el bounce se queda por debajo del 1 %: son mediciones nuestras, nunca cifras que prometamos.

La lista que Enrow no te va a montar

Enrow resuelve a gente que tú ya has identificado. Un email necesita un nombre completo y un dominio; 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 la resolución en tiempo real no, y prefiero quedarme sin función de búsqueda antes que sacar una caducada. Dentro de Clay eso no te cuesta nada, porque Find People, una sincronización con el CRM o un CSV ya han hecho ese trabajo antes: los criterios están en cómo elegir un proveedor de datos B2B.

Si lo que tienes montado es código y no un workbook, esas mismas consultas responden directamente. La API de Enrow te da una clave sin pasar por comercial, y ya hay SDK oficiales en siete lenguajes (JS/TypeScript, Python, PHP, Go, Java, Swift y Rust), todos en acceso anticipado y desde el código de 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?

Miran en direcciones opuestas. 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, devuelve 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, 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 el arreglo 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 revela contactos. 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 gratis cada mes, a principios de mes, durante el tiempo que quieras y sin pedirte tarjeta.