Exportar Mastodon por Período Específico: Como Filtrar com API

O Mastodon permite exportar seus dados pelo menu Preferências. Mas a ferramenta de exportação nativa não tem opção de limitar a exportação a um período específico. Você só pode exportar todos os seus toots, seguidores e listas de uma vez. Este artigo explica como usar a API do Mastodon para solicitar dados de um período personalizado. Você aprenderá a fazer chamadas de API que filtram suas postagens, favoritos e outros registros por data.

Como a API do Mastodon Lida com Filtragem por Data

A API do Mastodon não aceita strings de data diretas como 2024-01-01 na maioria dos endpoints. Em vez disso, ela usa IDs numéricos que codificam o momento de criação de cada registro. Cada toot, seguidor e favorito tem um ID inteiro único. O ID aumenta com o tempo. Registros mais novos têm IDs mais altos que os mais antigos.

Para filtrar por data, você primeiro precisa encontrar o ID que corresponde à data de início ou fim desejada. Em seguida, você passa esse ID como parâmetro since_id ou max_id na requisição à API. O servidor retorna apenas registros com IDs acima de since_id ou abaixo de max_id. Essa abordagem permite exportar dados de um mês, semana ou período personalizado específico.

Entendendo since_id e max_id

Os dois parâmetros funcionam da seguinte forma:

• since_id — Retorna apenas registros com ID maior que este valor. Use para obter dados após uma determinada data.
• max_id — Retorna apenas registros com ID menor ou igual a este valor. Use para obter dados antes de uma determinada data.

Combine ambos os parâmetros para definir uma janela. Por exemplo, para obter toots de janeiro de 2024, defina since_id como o ID do último toot de dezembro de 2023 e max_id como o ID do último toot de janeiro de 2024.

Pré-requisitos para Usar a API

Você precisa de três coisas antes de começar:

1. Uma conta no Mastodon com acesso à API
   Qualquer conta do Mastodon funciona. Você não precisa de permissões especiais para ler seus próprios dados.
2. Um token de acesso
   Gere um token em Preferências > Desenvolvimento > Nova Aplicação. Conceda pelo menos o escopo read.
3. Uma ferramenta para fazer requisições HTTP
   Você pode usar curl no terminal, Postman ou qualquer linguagem de programação com uma biblioteca HTTP.

Passos para Exportar Toots Dentro de um Período

Siga estes passos para exportar seus toots de um período específico. O mesmo método funciona para favoritos e seguidores com endpoints diferentes.

1. Obtenha seu ID de conta
   Envie uma requisição GET para https://suainstancia.social/api/v1/accounts/verify_credentials com seu token de acesso no cabeçalho Authorization. A resposta inclui um campo id. Copie esse número.
2. Encontre o ID para sua data de início
   Os IDs do Mastodon são baseados no timestamp Unix. Use uma ferramenta como o conversor de ID do Mastodon em https://mastodon.social/convert ou escreva um script que converta um timestamp em um ID do Mastodon. Para 1º de janeiro de 2024 às 00:00 UTC, o ID é aproximadamente 111111111111111111 (o valor real depende do tempo de atividade da instância).
3. Encontre o ID para sua data de fim
   Use o mesmo conversor para o último segundo do seu mês alvo. Para 31 de janeiro de 2024 às 23:59 UTC, converta esse timestamp para um ID.
4. Envie a requisição à API com o período
   Chame GET https://suainstancia.social/api/v1/accounts/:id/statuses?since_id=ID_INICIO&max_id=ID_FIM&limit=40. Substitua :id pelo seu ID de conta, ID_INICIO pelo ID do passo 2 e ID_FIM pelo ID do passo 3. O parâmetro limit controla quantos toots por página (máximo 40).
5. Lide com a paginação para exportações grandes
   Se você tiver mais toots que o limite, a resposta inclui um cabeçalho Link com uma URL next. Siga essa URL para obter a próxima página. A URL next já contém o max_id correto para o próximo lote.
6. Salve os resultados
   Escreva cada página da resposta em um arquivo JSON. Combine todos os arquivos depois para obter a exportação completa do seu período.

Exemplo de Comando curl para uma Única Página

Substitua suainstancia.social, SEU_ID_CONTA, ID_INICIO, ID_FIM e SEU_TOKEN pelos seus valores reais:

curl -H "Authorization: Bearer SEU_TOKEN" \
"https://suainstancia.social/api/v1/accounts/SEU_ID_CONTA/statuses?since_id=ID_INICIO&max_id=ID_FIM&limit=40"

Problemas Comuns e Como Evitá-los

Você Obtém uma Resposta Vazia Mesmo Tendo Postagens no Período

A causa mais provável é uma conversão de ID incorreta. Os IDs do Mastodon não são simplesmente o timestamp Unix multiplicado por 1000. Eles usam um algoritmo snowflake que inclui o deslocamento de timestamp interno da instância. Use o conversor oficial de ID do Mastodon ou calcule o ID usando o timestamp de criação da instância. Se sua instância for antiga, o ID para uma determinada data será maior do que em uma instância mais nova.

A API Retorna um Erro 401 Não Autorizado

Seu token de acesso pode não ter o escopo read ou ter expirado. Vá em Preferências > Desenvolvimento > Editar seu aplicativo e verifique os escopos. Regere o token se necessário. Certifique-se de incluir o token no cabeçalho Authorization como Bearer SEU_TOKEN.

A Paginação Para Antes de Todas as Postagens Serem Recuperadas

A API tem limites de taxa. Se você enviar requisições muito rápido, o servidor pode retornar um erro 429 Muitas Requisições. Aguarde o tempo especificado no cabeçalho Retry-After antes de continuar. Verifique também se você está seguindo exatamente a URL next do cabeçalho Link. Não modifique os parâmetros manualmente.

Endpoints da API do Mastodon para Exportações por Período

Tipo de Dado	Endpoint	Parâmetros de Filtro
Toots	GET /api/v1/accounts/:id/statuses	since_id, max_id, limit
Favoritos	GET /api/v1/favourites	max_id, since_id, limit
Seguindo (contas que você segue)	GET /api/v1/accounts/:id/following	since_id, max_id, limit
Seguidores	GET /api/v1/accounts/:id/followers	since_id, max_id, limit
Listas	GET /api/v1/lists	Sem filtro de data (todas as listas retornadas)

O endpoint de listas não suporta filtro de data porque listas são metadados, não registros cronológicos. Para bookmarks, use GET /api/v1/bookmarks com max_id e since_id.

Agora você pode exportar seus dados do Mastodon para qualquer período personalizado usando a API. Comece com um pequeno teste para verificar sua conversão de ID. Escreva um script que percorra os resultados paginados para automatizar exportações maiores. Para uso avançado, considere usar o parâmetro min_id em vez de since_id em alguns endpoints para melhor desempenho com dados muito antigos.