IG: como detectar problemas em perfis públicos antes do lançamento de uma campanha

Antes do lançamento de uma campanha, é possível processar uma lista de contas do IG com um script e obter um relatório JSON com a resposta da API para cada nome. O endpoint IG Scraper API da jsonscraper retorna um status externo e um objeto de perfil; o esquema observado inclui nome de usuário, indicadores de privacidade e verificação, número de publicações, seguidores e contas seguidas. Esses campos ajudam a selecionar registros para análise manual, mas, por si só, não explicam a causa de uma resposta ausente ou inesperada.

O problema: a lista de contas parece correta, mas está pronta para uso?

Uma planilha de trabalho da campanha pode conter contas renomeadas, erros de digitação e perfis privados. Se a equipe começar a analisar a lista sem uma verificação preliminar, alguém terá de abrir as contas uma a uma. Uma consulta automatizada reduz o trabalho manual e mantém um registro único do que a API retornou para cada nome solicitado.

O objetivo desse fluxo é limitado: percorrer a lista, salvar as respostas HTTP reais e o JSON, e separar para análise manual os perfis com características relevantes para a campanha. O relatório registra os dados observados; não determina por que um perfil não foi retornado nem por que a solicitação falhou.

O que a solicitação verifica

A documentação da jsonscraper especifica o endpoint GET \/v1\/user\/by\/username. O parâmetro obrigatório é username; a chave é transmitida como license_key. O parâmetro opcional cache_timeout ativa o armazenamento em cache pelo número de segundos especificado, enquanto 0 o mantém desativado. O esquema observado de uma resposta bem-sucedida contém um status externo e um objeto ig com campos do perfil.

Para diagnosticar, diferencie três fatos: se a solicitação HTTP foi executada; se o JSON analisado contém um objeto ig; e quais campos estão presentes nesse objeto. Se alguma etapa não ocorrer como esperado, o script pode registrar o resultado técnico e a resposta original. Esse resultado indica que é preciso investigar, mas não estabelece a causa da falha.

Prepare os dados de entrada e a chave

Crie o arquivo usernames.txt, com um nome de usuário por linha, sem o caractere @. Remova linhas vazias e duplicatas, mantendo apenas as contas relacionadas à campanha. Para comparar resultados posteriormente, registre separadamente a data da verificação e o identificador do projeto.

Armazene a chave na variável de ambiente JSONSCRAPER_INSTAGRAM_LICENSE_KEY, não no código-fonte nem no repositório:

export JSONSCRAPER_INSTAGRAM_LICENSE_KEY="sua_chave"
python3 check_profiles.py

O exemplo usa a biblioteca padrão do Python 3.8+ e não exige a instalação de pacotes HTTP.

Exemplo: solicitar perfis e salvar um relatório

O script percorre a lista, um nome por vez. Em caso de resposta JSON bem-sucedida, salva o corpo recebido e os campos de perfil disponíveis; em caso de erro HTTP ou de rede, registra o resultado técnico. Campos ausentes permanecem como null, e o corpo bruto da resposta é salvo se puder ser lido.

import json
import os
import time
from datetime import datetime, timezone
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

API_KEY = os.environ.get("JSONSCRAPER_INSTAGRAM_LICENSE_KEY")
if not API_KEY:
    raise SystemExit("Defina JSONSCRAPER_INSTAGRAM_LICENSE_KEY")

BASE_URL = "https:\/\/ig.jsonscraper.com\/v1\/user\/by\/username"

with open("usernames.txt", encoding="utf-8") as f:
    usernames = list(dict.fromkeys(
        line.strip().lstrip("@") for line in f if line.strip()
    ))

results = []
for username in usernames:
    params = urlencode({"username": username, "license_key": API_KEY})
    request = Request(f"{BASE_URL}?{params}", method="GET")
    checked_at = datetime.now(timezone.utc).isoformat()

    try:
        with urlopen(request, timeout=30) as response:
            http_status = response.status
            raw_body = response.read().decode("utf-8")
        try:
            payload = json.loads(raw_body)
            json_error = None
        except json.JSONDecodeError as exc:
            payload = None
            json_error = str(exc)

        profile = payload.get("ig") if isinstance(payload, dict) else None
        record = {
            "requested_username": username,
            "checked_at": checked_at,
            "http_status": http_status,
            "api_status": payload.get("status") if isinstance(payload, dict) else None,
            "check_result": "profile_returned" if isinstance(profile, dict) else "unexpected_or_missing_profile_object",
            "response": payload if payload is not None else raw_body,
        }
        if json_error:
            record["json_error"] = json_error
        if isinstance(profile, dict):
            record["returned_username"] = profile.get("username")
            record["is_private"] = profile.get("is_private")
            record["is_verified"] = profile.get("is_verified")
            record["media_count"] = profile.get("media_count")
            record["follower_count"] = profile.get("follower_count")
            record["following_count"] = profile.get("following_count")
        results.append(record)
    except HTTPError as exc:
        body = exc.read().decode("utf-8", errors="replace")
        results.append({
            "requested_username": username,
            "checked_at": checked_at,
            "check_result": "http_error",
            "http_status": exc.code,
            "response": body,
        })
    except (URLError, TimeoutError) as exc:
        results.append({
            "requested_username": username,
            "checked_at": checked_at,
            "check_result": "request_error",
            "detail": str(exc),
        })

    time.sleep(0.5)

with open("profile-check.json", "w", encoding="utf-8") as f:
    json.dump(results, f, ensure_ascii=False, indent=2)

print(f"Resultados salvos: {len(results)}")

Este é um exemplo de integração, não um relato de teste realizado. A chave é transmitida no parâmetro license_key, mas não é exibida. A resposta completa pode conter informações cujo acesso deve ser restrito conforme as regras de retenção de dados da sua equipe.

Como interpretar o resultado

O registro profile_returned significa que o script recebeu um objeto JSON ig. Compare requested_username com returned_username e examine os indicadores importantes para o processo da campanha. Por exemplo, is_private: true pode ser encaminhado para análise manual se a campanha exigir um perfil público.

Os resultados http_error, request_error e unexpected_or_missing_profile_object indicam apenas a etapa em que o script não obteve a estrutura esperada. Não provam que a conta foi excluída, está privada ou está inacessível por um motivo específico. Salve a resposta, confira o nome e a chave e, em seguida, repita a solicitação ou entre em contato com o suporte oficial do serviço.

Se um campo estiver ausente, mantenha-o como desconhecido — não interprete a ausência como zero ou false. Os contadores do perfil descrevem o estado retornado no momento da solicitação. A marca temporal permite distinguir esse instantâneo dos resultados de uma execução posterior.

Automatize sem perder a observabilidade

Agende a execução ou incorpore-a a uma etapa do processo ETL existente. Armazene a data da verificação, o nome solicitado, o resultado, o status e o corpo da resposta. Em uma etapa separada, você pode carregar o JSON em uma tabela e enviar ao especialista apenas os registros que precisam ser verificados.

Para detectar mudanças, compare os instantâneos de um mesmo perfil pelos campos escolhidos. Uma alteração no número de publicações é motivo para abrir o perfil e verificá-lo, não uma data exata de publicação. O número de seguidores também representa o valor no momento da solicitação; por isso, o histórico de observações é formado pelos instantâneos salvos.

Para listas grandes, defina um ritmo controlado, acrescente novas tentativas com limite e mantenha um registro de erros. Não inclua a chave nos logs da URL. Armazenar separadamente a lista de entrada e os resultados ajuda a identificar quais contas já foram processadas.

Resultado esperado

O resultado é um arquivo JSON com o processamento de cada nome informado, a marca temporal, os atributos disponíveis e a resposta salva. Antes de encaminhar a lista para a campanha, é possível filtrar nomes correspondentes, perfis privados e casos técnicos para análise manual. A própria equipe define os critérios para a etapa seguinte.

O endpoint e os parâmetros estão descritos na documentação da API do IG; as informações sobre o produto estão na página da IG Scraper API. Comece com uma amostra pequena, confira o formato real das respostas e ajuste as regras do relatório ao seu processo.