API do Clay e integrações: entradas, saídas e ligações à medida

O essencial O Clay tem uma API pública: https://api.clay.com/public/v0, um cabeçalho clay-api-key, 13 operações documentadas e uma especificação OpenAPI 3.1.0 de 67 151 bytes, disponível em developers.clay.com/openapi.json a 29 de agosto de 2026. Há outras cinco coisas a que se chama «a API do Clay» e que não o são — a coluna HTTP, uma fonte por webhook de entrada, um webhook de saída assinado, uma ação nativa de fornecedor, o servidor MCP. Planos diferentes, limites diferentes. Quando o Clay documenta um comportamento mas não publica número nenhum, esta página di-lo.

No mês passado, um responsável de RevOps reencaminhou-me um artigo como prova de que o Clay não tinha API. Ainda há muitos artigos a dizer o mesmo. Descrevem um produto que entretanto mudou: o URL base é público e a especificação descarrega-se sem um único erro. Fui buscá-la a 29 de agosto — 67 151 bytes, OpenAPI 3.1.0, 13 operações.

A plataforma para programadores nunca teve entrada própria no changelog, e daí que a resposta desatualizada continue bem posicionada. Segue-se o mapa completo das ligações: o que cria linhas, o que preenche células, aquilo a que o seu código consegue chegar e cada limite publicado.

O Clay tem API?

Tem. A API pública do Clay fica em https://api.clay.com/public/v0, autentica-se através de um cabeçalho clay-api-key gerado em Settings → Account → API keys — ainda com a etiqueta beta — e expõe 13 operações: uma verificação de identidade, execuções de rotinas, execuções em lote, as Searches e consultas a tabelas. Com uma chave recusada, a resposta é {"message": "Authentication failed"}, e as chaves devem ficar sempre do lado do servidor.

A especificação é legível por máquina, portanto o seu cliente pode ser gerado automaticamente a partir dela: o openapi.json declara info.title «Clay Public API», info.version «0» e um único esquema ClayApiKey. Não existe openapi.yaml.

Integrações do Clay: dez vias e como saber de qual precisa

As linhas entram por uma fonte ou não entram: a API pública lê tabelas, mas nunca as constrói.

A maior parte dos pedidos formulados como «precisamos da API do Clay» são, na verdade, uma fonte ou uma coluna. Distinguir as duas coisas pode ser a diferença entre um sprint e uma mudança de plano.

Antes de planear seja o que for à volta dessas últimas linhas da tabela, convém conhecer uma contradição. O university.clay.com/docs/clay-api-cli diz que a plataforma para programadores está «available across all Clay plans, including free and trial plans», e que as chamadas por API e por CLI gastam «the same credits and actions as the equivalent work done in-product». Já a FAQ de preços inclui o «Clay API access» entre os pontos do plano Enterprise, e a tabela comparativa não tem sequer linha de API. Confirme primeiro na sua área de trabalho. Duas notas do mesmo documento: a CLI e a API funcionam em Mac e em Linux, em beta aberta, mas não em Windows; e a beta do Agent Plugin corre nos planos atuais e ainda nos antigos até ao fim de 2026.

O Launch custa 185 $/mês, ou 167 $ com pagamento anual; o Growth, 495 $, ou 446 $. São valores em dólares americanos, porque é essa a moeda em que o Clay publica, e ficam aqui tal como estão, sem conversão — a grelha completa está em preços do Clay. O próprio Clay conta o seu diretório de fornecedores de três maneiras: «200+ providers» na navegação do site, «150+ data partners» na FAQ de preços, e 157 URL /integrations/data-provider/ distintos quando os contei em clay.com/integrations a 29 de agosto, repartidos por 24 categorias.

Rotinas: a unidade de trabalho que o seu código consegue chamar

Uma rotina é lógica do Clay com endereço próprio: cria-se uma função personalizada na interface, liga-se a integração por API, pega-se no id t_... e põe-se-lhe function: à frente.

Os trabalhos pequenos correm numa única chamada. O POST /routines/{routine_id}/run recebe um array items com um mínimo de 1 e um máximo de 100 — a página de referência do Clay chama-se «Execute a routine against 1-100 items», ou seja, o limite está no próprio título. Responde 202 com um routine_run_id e aceita um webhook_id opcional.

Já os trabalhos grandes exigem quatro chamadas: pedir um URL pré-assinado a run-batch/upload-url, fazer PUT do JSONL como application/x-ndjson, com linhas do género {"id": "row-1", "inputs": {"domain": "clay.com"}}, depois POST para run-batch/start e, no fim, GET /routines/run-batch/{id}/results. A CLI junta as quatro num só comando — clay routines runs start function:t_abc123 --bulk rows.jsonl — e o clay login --device trata da autenticação numa máquina sem ecrã.

As Searches interrogam a base GTM própria do Clay, por pesquisa avançada (em beta, com operadores booleanos aninhados) ou por filtros estruturados, dentro dos limites da tabela mais abaixo. Se ultrapassar um deles, recebe um HTTP 402 que indica qual. Uma ressalva: o university.clay.com/docs/clay-api-cli indica 10 000 resultados por pedido nos planos pagos self-serve, ao passo que o developers.clay.com/searches indica 500. Aqui sigo a documentação para programadores.

E há uma fronteira que nenhum resultado da primeira página do Google menciona. Nas palavras do Clay, há «no current plans to support table building via the developer platform». O Tables é só de leitura, existe apenas no Enterprise e consulta-se em POST /public/v0/tables/query; não há endpoint para listar tabelas. As linhas entram por uma fonte ou não entram — a ordem de montagem desse lado está em como usar o Clay.

O que o Clay responde quando uma chamada falha

O comportamento em caso de falha está documentado ao pormenor, mas não há um único número publicado sobre o limite a partir do qual o Clay trava os pedidos. Convém esclarecer isto antes de dimensionar um trabalho.

Quando bate no limite de pedidos por área de trabalho, recebe um HTTP 429, um Retry-After em segundos e os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset «when available». A CLI sinaliza-o com o código de saída 4. O conselho do Clay é tratar o 429 como um pedido a repetir mais tarde e «prefer batch and async endpoints over tight polling loops».

As respostas fora dos 2xx vêm em JSON, com uma message que uma pessoa consegue ler. O Clay afirma que «error response bodies do not currently include stable error codes», logo o seu switch tem de se basear no código de estado — 401 e 403 para autenticação, 404 para recurso inexistente, 409 e 422 para validação, 429 para excesso de pedidos, 5xx para falhas transitórias. E um 202 num endpoint assíncrono não é sucesso. Quer dizer que ainda está a correr.

A coluna HTTP API: ligar o Clay a uma fonte de que ele nunca ouviu falar

Esta coluna aponta o Clay para algo que está fora do seu diretório: «lets you send or retrieve data from any tool or database using an API endpoint, even when Clay doesn't offer a native integration», em GET, POST, PUT e DELETE. Todos os códigos de estado documentados para ela descrevem o endpoint que foi chamado, e não o Clay — é aí que se deve procurar quando uma coluna fica vermelha.

A última linha inverte a lógica habitual: o travão é o utilizador que o põe, não o Clay que o impõe. Faz-se em dois campos, Request limit e Duration (ms), e o exemplo dado pelo próprio Clay — 10 em 1 000 ms — dá dez pedidos por segundo.

Dois avisos sobre credenciais, ambos do Clay. Uma chave escrita à mão no campo Headers fica «visible in plain text to anyone with access to the table column», por isso o melhor é usar uma conta guardada. Mas atenção: editar uma dessas contas «will affect every HTTP API enrichment column across your workspace that uses it».

Os webhooks do Clay apontam para dois lados e só têm o nome em comum

Esvaziar a tabela não repõe nenhuma das 50 000 submissões, e um webhook de saída pode nunca chegar.

O webhook de entrada é uma fonte: clica-se em + Add no fundo de um workbook, procura-se Webhooks, escolhe-se Monitor webhook e copia-se o URL. O token de autenticação só se vê uma vez: «make sure to copy the token immediately, as you can only access authentication tokens once». Depois vem o limite que apanha as equipas de surpresa: uma fonte por webhook aceita 50 000 submissões, e essa contagem «persists even after deleting rows». Esvaziar a tabela não serve de nada; abaixo do Enterprise, cria-se outra fonte. O guia indica um plano «Explorer» que já não aparece na página de preços, por isso confirme o escalão na sua própria área de trabalho.

O de saída pertence à plataforma para programadores. O clay webhooks create https://example.com/hooks/clay devolve um id, um url, um createdAt e um signingSecret, com o aviso «store immediately, it can't be retrieved later». Os payloads trazem webhookId, createdAt e um objeto data, e são assinados no cabeçalho X-Clay-Signature: sha256=, seguido de um HMAC-SHA256 do corpo. E depois vem a frase que deve moldar a arquitetura, e não apenas o tratamento de erros: «Webhook delivery is not guaranteed. Use webhooks to react faster, but keep polling the run's results as a fallback.»

O Clay e o LinkedIn: os limites do Find People e o que faz de facto a extensão Chrome

É no Find People que costumam começar as listas de perfis do LinkedIn, dentro dos limites da tabela mais abaixo e com exclusões até 300 000 pessoas e 100 000 por fonte, repartidas por três conjuntos e cruzadas pelo URL do LinkedIn. A documentação do Clay nunca diz qual é a fonte de dados por trás disto, e eu também não a vou nomear.

É na extensão Chrome que mais gente se engana. Fica dito sem rodeios: a documentação do Clay descreve as duas extensões como ferramentas de extração, e não como ferramentas que revelam contactos. O Clay for Chrome extrai dados estruturados de uma página e mapeia campos como nome, site, LinkedIn ou Crunchbase para uma tabela. O Clip to Clay guarda páginas inteiras. Na Chrome Web Store, o Clay for Chrome tem 4,4 em 5 com 9 avaliações, 10 000 utilizadores, versão 1.0.0, atualizada a 10 de abril de 2025.

O MCP do Clay: a sua área de trabalho dentro de um assistente de IA

O servidor MCP do Clay liga uma área de trabalho ao Claude, ao ChatGPT, ao Microsoft Copilot e ao Glean, e administra-se em Settings → MCP users. Os controlos de créditos existem no Launch, no Growth e no Enterprise; os de audiência são exclusivos do Enterprise. A conta é exatamente a mesma do produto: «If a Function that finds someone's email and phone number costs 12 credits in a Clay table, it costs 12 credits when a rep triggers it from Claude or ChatGPT.» O agent plugin é outra coisa: a documentação para programadores descreve-o como um pacote que leva as skills do Clay e a CLI clay a agentes de programação como o Claude Code, o Codex e o Cursor — ou seja, corre num terminal e não num cliente de conversa.

Todos os limites que o Clay põe por escrito

Quase todos os limites do Clay ficam nos 50 000, e é o da fonte por webhook que deve orientar o desenho do resto, porque o seu contador sobrevive ao apagamento das linhas.

O enriquecimento em massa acima de 50 000 registos só existe no Enterprise. E há uma linha do documento de fontes do Clay que vale a pena ler antes de uma importação grande: quando se chega ao limite, «Clay imports records up to the limit and stops automatically. No error message is displayed». As saídas que o próprio Clay sugere são dividir o ficheiro por filtro ou por intervalo de datas, ou passar às tabelas com apagamento automático e ao enriquecimento em massa do Enterprise.

Acrescentar a Enrow como coluna na sua tabela

Nem o Clay nem a Enrow cobram uma pesquisa vazia: uma cascata de tentativas só paga quando há resultado.

A Enrow está no diretório do Clay desde 1 de setembro de 2024, nas categorias Contact Data e Contact Data Verification, numa integração construída pelo próprio Clay e etiquetada «Included in All Plans». São três ações que funcionam como colunas, e cada uma devolve um estado de qualificação junto com o resultado.

A nossa documentação regista um custo em créditos Clay nessa verificação, ao passo que a ficha do Clay lhe chama gratuita — confirme dentro da aplicação. Com chave própria, aponte uma coluna HTTP API para https://api.enrow.io/email/find/single, com os cabeçalhos x-api-key e Content-Type: application/json e o corpo {"company_domain": /company_domain, "fullname": "/first_name /last_name"}. A resposta é assíncrona, portanto passe um URL de webhook do Clay em settings.webhook, ou consulte o id da pesquisa no endpoint GET correspondente até obter o resultado. Ponha o Request limit a 10 e a Duration a 1000, para bater certo: todos os endpoints POST da Enrow permitem dez pedidos por segundo por chave, e um POST em lote conta como um único pedido mesmo que leve 5 000 emails lá dentro.

Agora, a parte que importa numa cadeia que repete pedidos. A regra do Clay: «if an enrichment returns no result, you're not charged Data Credits or Actions.» Do lado do fornecedor, a nossa é igual — só sai um crédito do saldo quando o resultado válido aparece; um contacto sem resultado não custa nada. Quando o resultado chega, um email custa 1 crédito Enrow, um telemóvel direto custa 40 e uma verificação custa um quarto, tudo do mesmo saldo de créditos. A ordem das colunas está tratada em cascatas de enriquecimento no Clay.

Cada endereço passa por mais de dez verificações, e os domínios catch-all são resolvidos e entregues em vez de carimbados como «arriscados». A taxa de contactos encontrados anda perto dos 60% e o bounce fica abaixo de 1% nos nossos próprios ficheiros — são medições que fazemos, nunca números que prometemos.

A lista que a Enrow não lhe monta

A Enrow encontra os contactos de pessoas que já identificou. Um email precisa de nome completo e domínio; um telemóvel, de um URL de perfil ou de um nome com contexto de empresa. Não há base nenhuma por trás para consultar, e por isso uma pesquisa como «todos os VP of Engineering em Amesterdão em empresas Série B» não devolve nada. É de propósito. Os dados guardados envelhecem sem ninguém dar por isso; os que se procuram em tempo real, não. Prefiro passar sem a funcionalidade de pesquisa a oferecer uma desatualizada. Dentro do Clay isso não lhe custa nada, porque o Find People, uma sincronização com o CRM ou um simples CSV já tratam desse trabalho antes — como escolher um fornecedor de dados B2B reúne os critérios.

Se o seu processo corre em código e não num workbook, as mesmas pesquisas fazem-se diretamente. A API da Enrow dá-lhe uma chave sem conversa com um comercial, com SDK oficiais já em sete linguagens — JS/TypeScript, Python, PHP, Go, Java, Swift, Rust — todos em acesso antecipado, a partir do código no GitHub. O servidor MCP EnrowAPI/enrow-mcp põe as mesmas três pesquisas ao alcance de um assistente, e o Claude ou o Cursor encontram um contacto sem tabela nenhuma pelo meio. O detalhe dos endpoints está em API de email finder.

FAQ

A API do Clay é gratuita?

A plataforma para programadores não tem sobretaxa. A documentação do Clay diz que está disponível em todos os planos, incluindo o gratuito e o de teste, e que as chamadas por API e por CLI gastam os mesmos créditos e as mesmas ações que o trabalho feito dentro do produto. O que limita é a quota do plano Free: 500 ações e 100 data credits por mês.

Qual é a diferença entre a HTTP API do Clay e a API pública do Clay?

Apontam em sentidos opostos. A HTTP API é uma coluna dentro de uma tabela do Clay que chama um endpoint de terceiros e escreve a resposta numa linha, e a tabela comparativa do Clay reserva-a ao plano Growth. A API pública, em https://api.clay.com/public/v0, é a interface que o seu próprio código chama de fora do Clay, para correr rotinas, lançar trabalhos em lote e consultar as Searches.

De que plano preciso para a HTTP API e para os webhooks do Clay?

Growth. A tabela comparativa do Clay marca «HTTP API integrations» e «Automate any signal via webhooks» como não incluídos no Free nem no Launch, e as ligações a CRM e a data warehouse ficam no mesmo escalão. A API pública, a CLI e o servidor MCP estão disponíveis em todos os planos, segundo a documentação para programadores.

Quais são os limites de pedidos da API do Clay?

O Clay publica o comportamento, mas não o número. A API pública impõe um limite de pedidos por área de trabalho, devolve um HTTP 429, envia o Retry-After em segundos e acrescenta o X-RateLimit-Limit, o X-RateLimit-Remaining e o X-RateLimit-Reset quando disponíveis. Não aparece na documentação nenhum valor de pedidos por segundo.

Consigo escrever dados numa tabela do Clay pela API?

Não. O Clay afirma que não há, para já, planos para permitir a construção de tabelas através da plataforma para programadores. O Tables é só de leitura, só existe no Enterprise e é consultado em POST /public/v0/tables/query com páginas de 100 linhas no máximo. As linhas entram por uma fonte.

Existe um limite de webhooks no Clay?

Existe, e é definitivo. Uma fonte por webhook do Clay aceita 50 000 submissões, e o Clay documenta que o limite «persists even after deleting rows»: esvaziar a tabela não repõe o contador. Abaixo do Enterprise, a solução é criar uma fonte nova; no Enterprise, as tabelas com apagamento automático levantam o limite.

O que faz a extensão Chrome do Clay?

Extrai o conteúdo de páginas, não revela contactos. O Clay for Chrome extrai dados estruturados de uma página web, de uma lista detetada automaticamente ou de um perfil individual, e leva-os para uma tabela do Clay, mapeando campos como nome, site, LinkedIn, Twitter ou Crunchbase. O Clip to Clay, a segunda extensão, guarda páginas web inteiras numa tabela.

O Clay tem servidor MCP?

Tem. Liga uma área de trabalho ao Claude, ao ChatGPT, ao Microsoft Copilot e ao Glean, gere-se em Settings → MCP users e tem controlos de créditos a partir do Launch, com a despesa reposta a zero no dia 1 de cada mês, à meia-noite UTC. O MCP não tem sobrecusto: 12 créditos numa tabela são 12 créditos a partir de um assistente.

Abra então a sua área de trabalho, faça a lista do que corre lá de verdade e ponha cada coisa numa linha da primeira tabela. A resposta à pergunta «isto dá para automatizar?» costuma já estar na conta, um escalão acima ou uma coluna ao lado.

Se o que lhe falta é um email verificado ou um telemóvel direto europeu, a Enrow está no diretório como uma coluna que pode ligar hoje mesmo. O plano gratuito dá 50 créditos no início de cada mês, sem limite de tempo, e não exige cartão, para a aplicação, a extensão Chrome e os assistentes de IA. Ligar a sua própria chave Enrow à coluna passa pela API, que abre com qualquer compra: um plano a partir de 15 €/mês ou um pacote de créditos sem subscrição.