API do Clay e integrações: como os dados entram, saem e se ligam à mão

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. Onde 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. Há muitos artigos por aí 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. Descarreguei-a 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 é por isso que a resposta antiga continua bem posicionada. O que se segue é o mapa completo das ligações: o que cria linhas, o que preenche células, aquilo a que o seu código consegue aceder, 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 com 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. Uma chave recusada recebe a resposta {"message": "Authentication failed"}, e as chaves ficam sempre do lado do servidor.

A especificação é legível por máquina, portanto pode gerar o cliente automaticamente: 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 de ligação, 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 do tipo «precisamos da API do Clay» resolve-se, na verdade, com uma fonte ou uma coluna. E entre uma e outra resposta pode estar a diferença entre um sprint e uma mudança de plano.

Antes de construir seja o que for à volta deste último bloco, tenha em conta 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 põe o «Clay API access» numa linha do plano Enterprise, e a tabela comparativa nem sequer tem uma linha para a API. Confirme primeiro na sua área de trabalho. Duas notas do mesmo documento: a CLI e a API são suportadas em Mac e em Linux, em beta aberta, mas não em Windows; e a beta do Agent Plugin funciona nos planos atuais e também 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 mantenho-os sem conversão; as grelhas completas estão em preços do Clay. O próprio Clay conta o 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 URLs /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 um endereço próprio: cria-se uma função personalizada na interface, ativa-se a integração por API, copia-se o id t_... e acrescenta-se-lhe o prefixo function:.

Os trabalhos pequenos executam-se diretamente. 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.

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 numa só (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 consultam a base GTM do próprio 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. Cito a documentação para programadores.

E há um limite que ninguém na primeira página de resultados menciona. O Clay escreve que tem «no current plans to support table building via the developer platform». O Tables é só de leitura, só no Enterprise, em POST /public/v0/tables/query, e não existe endpoint para listar tabelas. As linhas entram por uma fonte ou não entram; a ordem de montagem desse lado é explicada no guia sobre como usar o Clay.

O que o Clay diz quando uma chamada falha

O comportamento em caso de falha está documentado ao pormenor, e não há um único número publicado sobre o ponto exato em que o limite dispara. Convém ter isso em conta antes de dimensionar um trabalho.

Quando atinge o 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 Clay aconselha a repetir o pedido depois de um 429 e a «prefer batch and async endpoints over tight polling loops».

As respostas fora dos 2xx vêm em JSON, com uma message legível por humanos. O Clay afirma que «error response bodies do not currently include stable error codes», por isso o seu switch tem de se basear no código de estado: 401 e 403 para autenticação, 404 para recurso em falta, 409 e 422 para validação, 429 para limite de ritmo, 5xx para erros transitórios. E um 202 num endpoint assíncrono não significa sucesso. Quer dizer que o trabalho ainda está em curso.

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

Esta coluna liga o Clay a qualquer coisa que esteja 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 deve procurar quando uma coluna fica a vermelho.

A última linha inverte a lógica habitual: o limite é o utilizador que o define, não o Clay que o impõe. São dois campos, Request limit e Duration (ms), e o exemplo dado pelo próprio Clay, 10 em 1 000 ms, corresponde a 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 funcionam em dois sentidos 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 webhook 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, sobre o qual o Clay avisa: «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= com um HMAC-SHA256 do corpo. E depois vem a frase que devia orientar 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 a extensão Chrome faz de facto

É no Find People que costumam começar as listas ao estilo 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 também não serei eu a dizê-lo.

É sobre a extensão Chrome que quem pesquisa costuma enganar-se, por isso digo-o sem rodeios: a documentação do Clay descreve as duas extensões como ferramentas de extração, e não como ferramentas para obter contactos. A Clay for Chrome extrai dados estruturados de uma página e mapeia campos como nome, site, LinkedIn ou Crunchbase para uma tabela. A Clip to Clay guarda páginas inteiras. A ficha da Clay for Chrome mostra uma nota de 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 área de trabalho dentro de um assistente

O servidor MCP do Clay liga uma área de trabalho ao Claude, ao ChatGPT, ao Microsoft Copilot e ao Glean, e gere-se em Settings → MCP users. Os controlos de créditos estão disponíveis no Launch, no Growth e no Enterprise; os controlos de acesso são exclusivos do Enterprise. O consumo de créditos é exatamente o mesmo que no 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 é ainda outra coisa: a documentação para programadores descreve-o como a forma de disponibilizar as skills do Clay e a CLI clay a agentes de programação como o Claude Code, o Codex e o Cursor; ou seja, funciona num terminal e não num cliente de chat.

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 é aquele em função do qual deve planear o 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: uma vez atingido o limite, «Clay imports records up to the limit and stops automatically. No error message is displayed». As soluções que o próprio Clay sugere são dividir o ficheiro por filtro ou por intervalo de datas, ou passar para as tabelas com apagamento automático e para o enriquecimento em massa do Enterprise.

Pôr a Enrow numa coluna da 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 indica um custo em créditos Clay para essa verificação, enquanto a ficha do Clay a apresenta como 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 resposta. Defina o Request limit como 10 e a Duration como 1000, para coincidir com o nosso limite: todos os endpoints POST da Enrow aceitam dez pedidos por segundo por chave, e um POST em lote conta como um único pedido, mesmo que inclua 5 000 emails.

E agora a parte que importa numa cascata de tentativas. A regra do Clay: «if an enrichment returns no result, you're not charged Data Credits or Actions.» Do lado do fornecedor, a nossa regra é igual: só é debitado um crédito quando aparece um resultado válido, nunca numa falha, nunca num bounce. Quando o resultado chega, um email custa 1 crédito Enrow, um telemóvel direto custa 40 e uma verificação custa um quarto de crédito, tudo descontado do mesmo saldo. A ordem das colunas é explicada em cascatas de enriquecimento no Clay.

Cada endereço passa por mais de dez verificações, os domínios catch-all são resolvidos e entregues em vez de rotulados como «arriscados», e os telemóveis diretos europeus têm a documentação RGPD em ordem. A taxa de cobertura anda perto dos 60% e a taxa de bounce fica abaixo de 1% nos nossos próprios ficheiros: são medições que fazemos, não números que prometemos.

A lista que a Enrow não lhe monta

A Enrow encontra os contactos de pessoas que já foram identificadas. 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á nenhuma base por trás para consultar, por isso uma pesquisa como «todos os VP of Engineering em Amesterdão em empresas Série B» não dá resultado nenhum. É de propósito. Uma linha armazenada envelhece em silêncio, uma pesquisa em tempo real não, e prefiro não ter funcionalidade de pesquisa a ter uma desatualizada. Dentro do Clay isso não lhe faz falta, porque o Find People, uma sincronização com o CRM ou um simples CSV já fizeram esse trabalho; os critérios estão resumidos em como escolher um fornecedor de dados B2B.

Se o seu processo assenta em código e não num workbook, pode fazer as mesmas pesquisas diretamente. A API da Enrow dá-lhe uma chave sem ter de falar com um comercial, com SDK oficiais em sete linguagens (JS/TypeScript, Python, PHP, Go, Java, Swift, Rust), todos em acesso antecipado, com instalação a partir do código-fonte no GitHub. O servidor MCP EnrowAPI/enrow-mcp disponibiliza as mesmas três pesquisas a um assistente, para que o Claude ou o Cursor encontrem um contacto sem passar por nenhuma tabela. Os endpoints estão descritos em pormenor 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?

Funcionam 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 a partir de fora do Clay, para executar 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 ritmo 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 estão 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á planos, para já, para suportar a construção de tabelas pela plataforma para programadores. O Tables é só de leitura e só no Enterprise, 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 dados de páginas, não encontra contactos. A 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. A Clip to Clay, a segunda extensão, guarda páginas web inteiras numa tabela.

O Clay tem servidor MCP?

Tem, e liga uma área de trabalho ao Claude, ao ChatGPT, ao Microsoft Copilot e ao Glean, com gestão em Settings → MCP users, controlos de créditos a partir do Launch e o consumo reposto no dia 1 de cada mês, à meia-noite UTC. O MCP não tem custo adicional: 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 lá funciona de facto e associe cada coisa a uma linha da primeira tabela. A resposta à pergunta «isto dá para automatizar?» costuma já estar na sua conta, a um escalão de distância ou numa 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.