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, em linha 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 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á muito texto por aí a dizer o mesmo. Descrevem um produto que entretanto mudou: o URL base é público e a especificação descarrega sem um 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 velha continue a aparecer bem posicionada. O que se segue são as ligações todas: 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 num 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 responde {"message": "Authentication failed"}, e as chaves nunca saem do lado do servidor.

A especificação é legível por máquina, portanto o cliente pode gerar-se a si próprio: 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 superfícies, 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 escritos como «precisamos da API do Clay» são, na verdade, uma fonte ou uma coluna. E entre uma coisa e outra vai a diferença entre um sprint e uma mudança de plano.

Antes de desenhar seja o que for à volta desse último bloco, há uma contradição a levar consigo. 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 mete o «Clay API access» numa linha 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 estão suportadas em Mac e em Linux, em beta aberta, e 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 assim aqui sem conversão nenhuma — as escadas completas estão em preços do Clay. O diretório de fornecedores é contado de três maneiras pela própria casa: «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 morada: 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 ali mesmo. 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 são 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 arruma 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 interrogam a base GTM que é do próprio Clay, por pesquisa avançada (em beta, com booleanos encaixados) ou por filtros estruturados, dentro dos limites da tabela mais abaixo. Passe um deles e recebe um HTTP 402 a dizer qual foi. Uma ressalva: o university.clay.com/docs/clay-api-cli imprime 10 000 resultados por pedido nos planos pagos self-serve, ao passo que o developers.clay.com/searches imprime 500. Cito a documentação para programadores.

E a fronteira que ninguém na primeira página de resultados menciona. O Clay escreve que não há «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 está em 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 para o sítio onde o travão está posto. Convém resolver isso antes de dimensionar um trabalho.

Contra um 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 repetível 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 correr sobre o estado — 401 e 403 de autenticação, 404 em falta, 409 e 422 de validação, 429 de ritmo, 5xx transitório. 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 a alguma coisa que está fora do diretório dele: «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 procura quando uma coluna fica vermelha.

A última linha inverte a arrumação do costume: o travão é o utilizador que o põe, 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 — 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», portanto o melhor é usar uma conta guardada. Só que 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 a palavra em comum

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

O de entrada é uma fonte: + Add no fundo de um workbook, procurar Webhooks, escolher Monitor webhook, copiar 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 traz o selo de um plano «Explorer» que já não aparece na página de preços, portanto 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 que convém «store immediately, it can't be retrieved later». Os payloads trazem webhookId, createdAt e um objeto data, assinados em X-Clay-Signature: sha256= com um HMAC-SHA256 sobre o corpo. E depois a frase que devia desenhar 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 com feitio de 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 dizer.

Na extensão Chrome é que quem pesquisa adivinha mal, portanto 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. A Clay for Chrome tira dados estruturados de uma página e mapeia campos como nome, site, LinkedIn ou Crunchbase para dentro de uma tabela. A Clip to Clay guarda páginas inteiras. A ficha da Clay for Chrome dá 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 administra-se em Settings → MCP users. Os controlos de créditos chegam 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 ainda: a documentação para programadores descreve-o como a entrega das skills do Clay e da 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 são 50 000, e o da fonte por webhook é aquele à volta do qual se desenha o resto, porque o contador dele sobrevive ao apagamento das linhas.

O enriquecimento em massa acima de 50 000 registos é só no Enterprise. E há uma linha do documento de fontes do Clay que vale a pena ler antes de uma importação grande: chegado 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 partir o ficheiro por filtro ou por intervalo de datas, ou passar às tabelas com apagamento automático e ao enriquecimento em massa do Enterprise.

Dar uma coluna à Enrow dentro da sua tabela

Nem o Clay nem a Enrow cobram uma pesquisa vazia: uma cadeia com repetições 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 correm como colunas, e cada uma devolve um estado de qualificação ao lado do resultado.

A nossa documentação regista um custo em créditos Clay nessa verificação, onde 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é ele responder. 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.

E agora a parte que conta numa cadeia com repetições. 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, 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, tudo do mesmo saldo de créditos. A ordem das colunas está tratada em cascatas de enriquecimento no Clay.

Por trás de cada endereço estão mais de dez verificações, domínios catch-all resolvidos e entregues em vez de carimbados como «arriscados», e telemóveis diretos europeus com a documentação RGPD em ordem. 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 resolve 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á nada por trás para folhear, e por isso «todos os VP of Engineering em Amesterdão em empresas Série B» não devolve nada. É de propósito. Uma linha guardada envelhece em silêncio e uma resolução em tempo real não envelhece, e prefiro não ter a funcionalidade de pesquisa a ter 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á fizeram esse trabalho antes — como escolher um fornecedor de dados B2B arruma os critérios.

Se o seu processo for código e não um workbook, as mesmas pesquisas respondem diretamente. A API da Enrow dá uma chave sem passar por uma chamada 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 atrás de um assistente, de forma que o Claude ou o Cursor conseguem resolver 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 aperta é a dotação do 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 prende-a no plano Growth. A API pública, em https://api.clay.com/public/v0, é a superfície que o seu próprio código chama de fora do Clay, para correr rotinas, arrancar 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 correm 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 e não publica 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 os tem 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á, de 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 contador nenhum. Abaixo do Enterprise, a saída é 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 páginas, não revela contactos. A Clay for Chrome tira 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 a despesa reposta no dia 1 de cada mês, à meia-noite UTC. Não há prémio nenhum a pagar pelo MCP: 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 dentro da conta, a um escalão de distância ou a 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 prazo para acabar, e não pede cartão nenhum para isso.