Como Exportar Listas do Mastodon com API Além das Configurações Padrão

As listas do Mastodon permitem organizar contas seguidas em feeds temáticos. A exportação padrão da interface web inclui apenas nomes de listas e IDs dos membros, sem metadados como datas de criação, descrições ou detalhes das contas. Essa limitação dificulta arquivar ou migrar listas com contexto completo. Este artigo explica como usar a API REST do Mastodon para exportar listas com dados adicionais além das configurações padrão.

Entendendo os Endpoints da API de Listas do Mastodon e as Limitações Padrão

A API do Mastodon fornece dois endpoints principais para dados de listas. O endpoint GET /api/v1/lists retorna um array JSON de objetos de lista. Cada objeto contém o id, title e replies_policy da lista. O endpoint GET /api/v1/lists/:id/accounts retorna as contas que pertencem a uma lista específica. Cada objeto de conta inclui id, username, acct, display_name, url, avatar e outros campos do perfil.

O recurso de exportação padrão na interface web do Mastodon gera apenas um arquivo CSV com nomes de listas e IDs das contas membros. Ele não inclui o replies_policy da lista, nem display_name ou URLs dos membros. Essa exportação limitada perde contexto útil ao migrar entre instâncias ou auditar a composição das listas.

Campos da Resposta da API Disponíveis Além da Exportação Padrão

Ao chamar o endpoint de contas da lista, cada objeto de conta contém estes campos que a exportação padrão omite:

• display_name: O nome de exibição definido pelo usuário da conta.
• acct: O handle completo da conta, incluindo o domínio da instância.
• url: O link direto para o perfil da conta na instância.
• avatar: A URL da imagem do avatar da conta.
• note: A biografia ou descrição da conta.
• created_at: O timestamp de criação da conta no Mastodon.

O objeto da lista em si inclui o campo replies_policy, que controla se as respostas aos membros da lista aparecem no feed da lista. Esse campo não é exportado pelo CSV padrão.

Pré-requisitos para Exportação de Listas via API

Antes de exportar listas pela API, você precisa de três coisas:

1. Criar um token de aplicação no Mastodon
   Vá em Preferências > Desenvolvimento > Nova Aplicação. Defina o nome da aplicação. Em Escopos, marque a opção read:lists. Você também pode marcar read:accounts se quiser detalhes completos das contas. Clique em Enviar. Copie a string do token do campo Seu token de acesso.
2. Escolher uma ferramenta cliente de API
   Você pode usar qualquer cliente HTTP que suporte autenticação Bearer token. Ferramentas comuns incluem curl (linha de comando), Postman (GUI) ou um script personalizado em Python usando a biblioteca requests. Este guia usa comandos curl para clareza.
3. Saber a URL base da sua instância Mastodon
   A URL base é o endereço do seu servidor Mastodon, por exemplo https://mastodon.social ou https://suainstancia.com. Todas as requisições à API começam com essa URL seguida de /api/v1/.

Passos para Exportar Todas as Listas com Detalhes Completos dos Membros

Os passos a seguir recuperam todas as listas da sua conta e exportam cada lista com todos os campos disponíveis das contas membros em um arquivo JSON estruturado.

1. Obter a lista de todas as listas
   Execute este comando curl, substituindo SEU_TOKEN pelo seu token de acesso e SUA_INSTANCIA pela URL da sua instância:
   curl -H "Authorization: Bearer SEU_TOKEN" https://SUA_INSTANCIA/api/v1/lists
   A resposta é um array JSON. Cada objeto tem um campo id. Anote o id de cada lista que deseja exportar.
2. Exportar membros de uma única lista
   Para cada id de lista, execute este comando, substituindo ID_DA_LISTA pelo id real:
   curl -H "Authorization: Bearer SEU_TOKEN" https://SUA_INSTANCIA/api/v1/lists/ID_DA_LISTA/accounts
   A resposta é um array JSON de objetos de conta com todos os campos disponíveis.
3. Salvar a saída em um arquivo
   Adicione > lista_ID.json a cada comando curl para salvar a saída. Por exemplo:
   curl -H "Authorization: Bearer SEU_TOKEN" https://SUA_INSTANCIA/api/v1/lists/12345/accounts > lista_12345.json
4. Combinar todas as exportações de listas em um único arquivo
   Use um script para iterar sobre todos os ids de lista e mesclar os resultados. O script Python a seguir faz isso em uma única passada:

   import requests
   import json
   
   base_url = "https://SUA_INSTANCIA"
   token = "SEU_TOKEN"
   headers = {"Authorization": f"Bearer {token}"}
   
   # Obter todas as listas
   response = requests.get(f"{base_url}/api/v1/lists", headers=headers)
   lists = response.json()
   
   all_data = []
   for lst in lists:
       list_id = lst["id"]
       resp = requests.get(f"{base_url}/api/v1/lists/{list_id}/accounts", headers=headers)
       accounts = resp.json()
       all_data.append({
           "list_id": list_id,
           "list_title": lst["title"],
           "replies_policy": lst.get("replies_policy"),
           "members": accounts
       })
   
   with open("exportacao_todas_listas.json", "w") as f:
       json.dump(all_data, f, indent=2)
   

5. Verificar o arquivo exportado
   Abra exportacao_todas_listas.json em um editor de texto ou visualizador JSON. Cada entrada de lista inclui o título da lista, replies_policy e um array de objetos de conta membro com dados completos do perfil, incluindo display_name, acct, url e created_at.

Problemas Comuns na Exportação e Como Resolvê-los

API retorna erro 401 Não Autorizado

Esse erro significa que seu token está ausente ou inválido. Verifique se você copiou o token exatamente, sem espaços extras. Certifique-se de que o token tenha o escopo read:lists. Se você criou o token antes de adicionar o escopo, exclua-o e crie um novo.

API retorna erro 404 Não Encontrado para um id de lista

Esse erro ocorre quando o id da lista não existe na sua conta ou a lista pertence a outro usuário. Apenas ids de lista retornados pelo endpoint /api/v1/lists são válidos para sua conta. Não adivinhe nem reutilize ids de lista de outra instância.

Arquivo de exportação está vazio ou contém um array vazio

Um array vazio [] para uma lista significa que a lista não tem membros. Isso é normal para listas recém-criadas. Se você esperava membros, verifique se adicionou contas à lista através da interface web do Mastodon antes de exportar.

Limitação de taxa causa exportações incompletas

As instâncias do Mastodon impõem limites de taxa nas chamadas de API. Se você tiver muitas listas, o script pode atingir o limite e retornar erros HTTP 429. Para evitar isso, adicione um atraso entre as requisições. No script Python, insira time.sleep(1) dentro do loop após cada requisição de contas.

Exportação Padrão vs Exportação via API: Comparação de Recursos

Item	Exportação CSV Padrão	Exportação JSON via API
Título da lista	Sim	Sim
replies_policy da lista	Não	Sim
ID da conta membro	Sim	Sim
display_name do membro	Não	Sim
Handle acct do membro	Não	Sim
URL do perfil do membro	Não	Sim
URL do avatar do membro	Não	Sim
created_at do membro	Não	Sim
Formato de exportação	CSV	JSON
Autenticação necessária	Sessão web	Token OAuth Bearer

Agora você pode exportar listas do Mastodon com metadados completos usando a API. A saída JSON preserva as políticas das listas e perfis completos das contas. Em seguida, tente usar o campo replies_policy para filtrar feeds de lista com mais precisão. Para automação avançada, agende o script Python com um cron job para manter suas exportações atualizadas.