Referência
Referência da API de backlinks: ações, custos e erros
Uma página com os fatos que um monitor precisa saber: quanto custa cada ação, como funciona a paginação e o que a API faz quando algo dá errado.

Ações por custo em créditos
| Custo | Ações | Notas |
|---|---|---|
| Grátis, sem chave | domain, overview, stats, suggest | Ideal para dashboards e o verificador de DR |
| 1 crédito | bulk_dr, compare, top, dr_distribution, tld_breakdown | bulk_dr aceita até 2.000 domínios (GET domains= ou corpo POST); compare até 20 |
| 2 créditos | refdomains, backlinks, anchors, toppages, anchor_cloud, intersect | intersect aceita de 2 a 10 domínios |
| 3 créditos | search, keyword | Busca de texto completo em âncoras, títulos e URLs; keyword encontra quem está vinculado com uma âncora exata |
Autenticação e códigos de status
Passe a chave como key= ou como cabeçalho bearer. Verifique o código HTTP antes de analisar o corpo.
# header style
curl -s -H "Authorization: Bearer sk_live_..." \
"https://seouptr.com/api.php?action=anchors&q=yourdomain.com&per=100"
# a cron-safe wrapper
code=$(curl -s -o out.json -w '%{http_code}' "$URL")
case "$code" in
200) jq '._credits' out.json ;; # cost and remaining balance
401) echo 'bad or missing key' ;;
402) echo 'out of credit: top up' ;;
*) echo "unexpected $code" ;;
esacParâmetros e erros
| Item | Valor | Significado |
|---|---|---|
q | um domínio | O alvo da consulta |
page, per | per de 10 a 5000 | Paginação; o número de linhas por chamada é limitado a 1.000, paginação profunda limitada a 50.000 |
sort, order | order=asc ou desc | Ordenação das linhas retornadas |
ok | em todas as respostas | Se a chamada foi bem-sucedida |
_credits | apenas respostas autenticadas | Custo da chamada e saldo restante |
| HTTP 401 | chave ausente ou inválida | Verifique a chave ou o cabeçalho |
| HTTP 402 | créditos esgotados | Recarregue com USDT (TRC-20) |

Projetando a chamada antes de agendá-la
A maioria dos problemas da API começa na solicitação. Não na resposta. Uma integração de api de backlinks seo é principalmente um conjunto de pequenas decisões tomadas antes da primeira chamada. Defina a chave, o tamanho da página e a ordem de classificação primeiro.
Mantenha a chave fora do script
Armazene a chave em uma variável de ambiente ou em um repositório de segredos, não em um arquivo que você faz commit. Passe-a como o parâmetro key ou como um cabeçalho bearer. O cabeçalho mantém a chave fora de endereços que tendem a acabar em logs.
Não cole uma chave ativa em um ticket ou chat. Trate uma que apareça em um log compartilhado como exposta.
Escolha o tamanho da página com propósito
O parâmetro per varia de 10 a 5000, mas uma chamada é cobrada uma vez para até 1.000 linhas, então páginas maiores significam menos cobranças. Digamos que você precise de 3.400 linhas. Isso requer quatro chamadas de 1.000 linhas, não 340 chamadas de 10.
Mantenha o tamanho da página igual entre execuções para que os arquivos fiquem alinhados.
Fixe a ordem de classificação
Defina sort e order explicitamente em vez de confiar em um padrão. Parâmetros idênticos tornam a saída comparável de semana para semana, para que um diff mostre mudança real e não linhas reorganizadas.
Uma ordem alterada é uma maneira fácil de criar um alarme falso.
Lendo os números
Os dados são nosso próprio grafo de links: 181.132.097 domínios, 2.774.625.913 links entre domínios e cerca de 798,5 bilhões de backlinks. É atualizado aproximadamente uma vez por mês. Qualquer coisa mais recente que isso não estará nele, é por isso que uma api de backlinks seo é melhor consultada semanalmente.
DR é round(100 · log(ref_domains+1) / log(2·10^7)). É um log. Por isso, 100 domínios de referência pontuam 27, 1.000 pontuam 41 e 10.000 pontuam 55, então dobrar sua contagem de links adiciona apenas alguns pontos. Use DR para classificar sites entre si e a contagem bruta para alertas, como a tabela de severidade faz.
O preço é pré-pago. Não há assinatura e não há mínimo. O crédito de cadastro é $100, que equivale a 1.000.000 de créditos. Compare isso com as unidades da API Ahrefs, vendidas dentro de planos a partir de $129/mês por 200.000 unidades, com pelo menos 50 unidades por solicitação.
O planejamento de custos é uma simples multiplicação. Uma chamada semanal de refdomains para um site custa 2 créditos vezes 4, ou 8 créditos por mês, que é $0,0008. Dez sites custam dez vezes isso. A receita de link perdido e a tarefa de concorrente usam apenas ações da tabela acima.
Lendo um erro sem adivinhar
Um código de erro diz a quem deve agir. Leia dessa forma. A resposta então se torna uma decisão de roteamento, não um mistério. Os dois códigos que mais importam para um monitor são 401 e 402.
401 e 402 são problemas diferentes
Um 401 significa que a chave está ausente ou errada, e nada funcionará até que alguém corrija isso. Um 402 significa que a conta está sem crédito, e um recarregamento resolve. Encaminhe-os para diferentes responsáveis para que a pessoa certa veja a mensagem.
Envie ambos para uma pessoa. Um monitor que falha silenciosamente é pior do que um que nunca foi executado.
Verifique o status antes do corpo
Leia o status HTTP primeiro e o campo ok em segundo. Uma resposta pode ser analisada como JSON e ainda carregar uma falha, então a verificação está completa apenas quando ambas passam. Registre o status em cada execução, inclusive as bem-sucedidas.
Retente apenas o que pode se recuperar
Retentar um 401 desperdiça chamadas e preenche logs com a mesma falha. Um tempo limite de rede é diferente. Retente-o um pequeno número de vezes com uma pausa entre as tentativas, depois pare.
Uma execução que para e alerta é mais útil do que um loop de retentativa que esconde a falha até que o saldo acabe.
Registre o status em cada execução
Escreva o status HTTP e o saldo no log em cada execução, incluindo as bem-sucedidas. Quando uma execução falhar três semanas depois, essa linha será a primeira coisa que você vai querer ver.
domain, overview, stats e suggest não precisam de chave e não custam nada. Use-os para verificar a sanidade de um nome de domínio, uma ortografia exata ou um tamanho aproximado antes de gastar um único crédito em uma ação paga.
Antes de colocar uma chamada no cron
- O custo da ação é conhecido e multiplicado por execuções por mês.
- Código de saída e status HTTP são verificados.
- Um 402 envia um alerta para um humano.
- As respostas são salvas ordenadas, para que os diffs fiquem limpos.
- A cadência corresponde à atualização mensal.

Notas sobre paginação
A ordem importa. Use per=1000 para snapshots e mantenha o mesmo sort e order todas as semanas. Se a ordem mudar entre as execuções, um diff mostrará ruído. Essa é uma causa clássica de alarmes falsos.
Sites maiores? Para um site com mais de 1.000 domínios de referência, navegue com page=1, page=2 e assim por diante. Cada página é uma chamada cobrada separadamente. A paginação profunda é limitada a 50.000 linhas, o que cobre quase todos os sites comuns.
Perguntas sobre a referência
- Qual ação devo chamar primeiro quando não tenho certeza de como um domínio se parece?
- Comece com
overviewoudomain. Ambas são gratuitas e não precisam de chave, e mostram um tamanho aproximado e a forma básica dos dados. Gaste créditos emrefdomainsouanchorsapenas depois disso. - Quanto custa uma verificação completa de um domínio?
- Some os créditos de cada ação, depois multiplique por quantas vezes ela é executada. Imagine uma chamada
refdomains, uma chamadaanchorse uma chamadatld_breakdownem um domínio, semanalmente. Isso é 2 + 2 + 1 = 5 créditos por execução, ou $0,0005. Em quatro semanas, chega a cerca de $0,002. - Por que duas contagens para o mesmo domínio podem não coincidir?
- Compare o semelhante com o semelhante: a mesma ação, os mesmos parâmetros e o mesmo período de atualização. Contagens de ações diferentes não são intercambiáveis, e uma contagem feita durante a atualização pode diferir de uma feita uma semana depois.
- Como testar um job cron sem gastar créditos?
- Execute as ações gratuitas primeiro para verificar a fiação, o tratamento de status e o formato de saída. Depois, faça uma chamada paga para provar os números e limite o job a uma única execução enquanto testa.
- A paginação funciona para um site com mais de 1.000 domínios de referência?
- Sim. Use
pagecomper. Cada página é uma chamada cobrada separadamente, e a paginação profunda é limitada a 50.000 linhas, o que cobre a maioria dos sites comuns.
Um monitor que sobrevive a uma semana ruim
Um monitor ganha confiança nas semanas em que nada dá certo. Planeje uma resposta lenta, um saldo alterado e um resultado parcial antes da primeira execução. Esses são eventos comuns. Cada um deve deixar uma linha clara no log.
Timeouts e extrações parciais
Defina um timeout em cada chamada, para que uma resposta lenta não possa manter todo o job aberto. Se uma página de uma extração de várias páginas falhar, registre qual página foi e reinicie a partir daí. Você evita pagar duas vezes por linhas que já tem.
Marque um arquivo parcial como parcial em vez de salvá-lo como um snapshot normal. Caso contrário, o próximo diff mostrará uma perda que nunca aconteceu.
Verificações de saldo
Leia _credits em cada resposta autenticada e escreva o saldo restante no log. Um pequeno script pode compará-lo com um piso que você escolher e enviar um aviso antes da próxima execução.
Digamos que o piso seja 500 créditos. Uma execução semanal que custa 40 créditos deixa margem para recarregar antes que um 402 chegue no meio da noite.
Mantenha cada job entediante
Dê a cada job um arquivo e um agendamento. Uma entrada cron que faz três coisas pode falhar de três maneiras, e o log nem sempre pode dizer qual aconteceu. Dois jobs pequenos são mais fáceis de confiar do que um inteligente.
Combine o agendamento com a atualização
Combine o agendamento do job com a atualização mensal em vez do relógio. Uma execução diária retorna o mesmo arquivo na maioria dos dias, o que adiciona custo e ruído sem adicionar informações. Semanalmente geralmente é suficiente.