Solicitação cURL
POST /api/v1/bulk-taskscurl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=tg_profile_batch \
-F country=US \
-F file=@numbers.txt
Produto em massa tg_profile_batch
Perfil por número do Telegram · Em massa
Envie números: ID de usuário do Telegram, nome de usuário, dias de atividade e URL da foto de perfil, além de idade, gênero e tom de pele reconhecidos na foto.
Um complemento para listas grandes inteiras — para poucos identificadores, a verificação em tempo real responde na mesma solicitação. Verificação em tempo real →
Contrato da API
Duas etapas: envie o arquivo e depois consulte a tarefa
O envio retorna um ID de tarefa imediatamente; consulte a tarefa por esse ID e, quando ela for concluída com sucesso, a resposta trará o link de download do arquivo de resultado. Cada solicitação é exibida com a respectiva resposta.
1. Envie o arquivo
O ID da tarefa volta imediatamente com preparing definido como true enquanto o arquivo é preparado em segundo plano: linhas inválidas, duplicadas e — em tarefas de números — números sem código do país ou de outro país são removidos e não são cobrados. O saldo é reservado para as linhas enviadas e liquidado na conclusão; a diferença é reembolsada.
Resposta: tarefa criada
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "tg_profile_batch",
"status": "processing",
"country": "US",
"submitted_lines": 1015,
"total": 1015,
"invalid_cnt": 0,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 0,
"preparing": true,
"created_at": "2026-09-08T09:30:00Z"
}
}2. Consulte a tarefa
Consulte pelo ID da tarefa. Quando a preparação termina, submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, em que total é o que é verificado e cobrado. Uma resposta de sucesso traz as contagens de sucesso e de falha e o link de download do arquivo de resultado; uma tarefa recusada durante a preparação fica como failed com reason_detail e é reembolsada integralmente.
Solicitação cURL
GET /api/v1/bulk-tasks/{id}curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"Resposta: tarefa concluída
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "tg_profile_batch",
"status": "success",
"country": "US",
"submitted_lines": 1015,
"total": 1000,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 12,
"preparing": false,
"success_cnt": 990,
"failure_cnt": 10,
"result_url": "https://…/result.csv",
"created_at": "2026-09-08T09:30:00Z"
}
}Como funciona
O que acontece com uma tarefa em massa
A verificação em massa não é a verificação em tempo real em escala maior — você envia uma vez, ela roda em segundo plano e você coleta depois. Não é preciso manter a página aberta; o estado da tarefa e os resultados ficam no seu painel.
01Envie o arquivo
Um .txt ou .csv com um número por linha. Ele é transmitido diretamente; nada é gravado em disco.
02Pré-verificação e reserva
Problemas óbvios (arquivo vazio, formato incorreto, poucas linhas) são rejeitados no envio. Em seguida, o saldo é reservado e o arquivo é preparado em segundo plano: linhas duplicadas e inválidas são removidas e a regra de país é verificada. Um arquivo que falha nessa etapa termina como tarefa com falha, reembolsada integralmente; caso contrário, apenas as linhas restantes são verificadas, e a tarefa é liquidada ao ser concluída.
03Execução em segundo plano
A tarefa é executada sozinha — feche a página se quiser. Uma falha é informada imediatamente e reembolsada integralmente.
04Baixe o resultado
Obtenha o arquivo na página de verificação em massa. Você paga apenas pelos itens que efetivamente retornaram resultado; a diferença é reembolsada.
Campos do resultado
Colunas do arquivo de resultado
O download é um único arquivo CSV com a tabela de resultados completa.
Colunas do arquivo de resultado
identifier·17253100591— O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).activated·true— Se o número está registrado no Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.uid·1234567890— ID de usuário do Telegram.username·alex_kim— Nome de usuário; vazio quando a conta não tem um.activedays·9— Dias desde que a conta foi vista pela última vez, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato em que foi vista por último, o Telegram revela apenas um intervalo, e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo).avatar_url·https://telegram.waavatar.xyz/v/example.jpg— URL da foto de perfil; vazia quando a conta não tem foto de perfil.age·31— Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.gender·male— Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.skin_color·white— Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
Ideal para
Quando recorrer a este produto
Segmentação de listas
activatedactivedaysavatar_urlAgrupe números do Telegram por resultado da conta, atividade recente e disponibilidade de foto de perfil antes de uma ação de contato ou da revisão da lista.
Exemplo: priorize contas ativas com foto de perfil utilizável nas operações de contato.
Enriquecimento de dados de contato
uidusernameavatar_urlAdicione IDs do Telegram, nomes de usuário e links de fotos de perfil aos contatos existentes para que as equipes reconheçam e eliminem duplicatas mais rápido.
Exemplo: transforme uma lista bruta de telefones em uma tabela de perfis pronta para contato.
Revisão de público
activedaysagegenderMantenha a atividade e os atributos baseados na foto de perfil em um único arquivo de resultado para organização de público e revisão manual.
Exemplo: separe contas ativas recentemente de perfis inativos ou incompletos.
Verificação da qualidade dos perfis
avatar_urlagegenderskin_colorUse a foto de perfil e seus atributos estimados para identificar registros que precisam de enriquecimento, verificação ou tratamento cuidadoso.
Exemplo: sinalize para acompanhamento contas com número registrado, mas sem foto de perfil utilizável.
Resposta direta
O que é a Perfil por número do Telegram em massa?
A consulta em massa de fotos de perfil do Telegram retorna, para cada número registrado, o ID de usuário, o nome de usuário, os dias de atividade, a URL da foto de perfil e os atributos reconhecidos nela: idade, gênero e tom de pele. Escolha no envio o país ao qual os números pertencem.
Limites claros
Limites deste produto
- Os resultados refletem o momento em que a tarefa foi executada. Fotos de perfil mudam — execute-a novamente para obter um estado atualizado; os resultados armazenados nunca são atualizados automaticamente.
- Não é uma verificação de alcançabilidade nem de atividade, nem verificação de identidade.
- Nada é enviado aos identificadores do arquivo.
- As colunas retornadas dependem da plataforma. Elas estão listadas nesta página antes do envio.
- Os links de download expiram. Baixe o arquivo logo após o término da tarefa; se um link expirar, consulte a tarefa novamente para obter um novo.
Quando a verificação em massa se encaixa
Quando a verificação em massa vale a pena — e quando a em tempo real é mais rápida
| Verificação em tempo real | Verificação em massa | |
|---|---|---|
| Quantos identificadores | 1 identificador por verificação única; vários por solicitação múltipla — os limites exatos estão na documentação da API | Uma lista grande inteira em uma única tarefa — a faixa de tamanho atual está na página de preços |
| Obtenção dos resultados | Imediata: os endpoints único e múltiplo respondem na mesma resposta; o painel os retorna um a um | Baixe um arquivo de resultado quando a tarefa terminar |
| País | Nada a escolher — as consultas em tempo real são enviadas uma a uma, sem agrupamento por país | Um país por tarefa, escolhido no envio e enviado junto com o arquivo |
| Formato do resultado | JSON, campos por item | Arquivo de resultado (um CSV com a tabela completa) |
| Uso típico | Validação de formulários, consultas de atendentes, bloqueio antes do envio | Higienização de listas, filtragem antes de campanhas, limpeza de dados armazenados |
Perguntas frequentes do produto
Sobre a Perfil por número do Telegram
Quando devo usar a verificação em massa em vez da verificação em tempo real?
Use a verificação em massa para uma lista grande inteira. Para poucos identificadores, a verificação em tempo real responde na mesma solicitação, sem tarefa para agendar.
O que acontece com os identificadores inválidos do arquivo?
A pré-verificação descarta as linhas malformadas, então elas nunca entram na contagem cobrável. Dos números restantes, os que o serviço de origem não consegue resolver também não são cobrados. Você paga apenas pelos números que efetivamente retornam resultado.
Quanto tempo leva uma tarefa?
Depende da quantidade de itens e do produto. Você pode fechar a página após o envio; a tarefa é executada em segundo plano e o resultado fica aguardando você na página de verificação em massa.
Sou reembolsado se falhar?
Sim. Uma tarefa com falha é reembolsada integralmente. Se a tarefa for bem-sucedida, mas alguns itens não retornarem nada, essa parte é reembolsada automaticamente. A diferença entre o valor reservado e o valor efetivamente cobrado sempre é devolvida.
Produtos relacionados
Outros produtos em massa
Análise de foto de perfil do WhatsApp · Em massaEnvie um arquivo inteiro de números: URL da foto de perfil do WhatsApp e o que a foto mostra — categoria, idade, gênero, tom de pele e cor do cabelo.Perfil por nome de usuário do Telegram · Em massaEnvie nomes de usuário do Telegram: ID de usuário, dias de atividade e URL da foto de perfil de cada conta.
Perfil por número do Viber · Em massaEnvie números: ID de membro do Viber, dias de atividade e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.
Perfil por número do MAX · Em massaEnvie números: ID de usuário do MAX, URL da foto de perfil e gênero.
Análise de foto de perfil do LINE · Em massaEnvie números: ID de usuário do LINE e URL da foto de perfil, além de categoria, idade, gênero, tom de pele e cor do cabelo reconhecidos na foto.
Perfil por número do Zalo · Em massaEnvie números: ID de usuário do Zalo e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.
Verificação de foto de perfil de e-mail · Em massaEnvie endereços Gmail, Yandex ou Mail.ru: se cada um é entregável e sua foto de perfil.Crie uma conta para enviar uma tarefa em massa
As verificações em massa e em tempo real usam o mesmo saldo — não há nada extra para ativar. Cadastre-se e envie seu primeiro arquivo na página de verificação em massa.