Referência da API

Exportações

Uma exportação gera um arquivo com todos os leads que correspondem aos seus filtros, para volumes grandes demais para paginar. Crie a exportação, consulte até o status dela ser ready e baixe a url. Você pode criar 10 exportações por hora por conta.

Com type definido como conversations, o arquivo traz, em vez dos leads, todas as conversas por DM da conta, cada uma com o seu lead e todas as mensagens desde a primeira. Ele serve para analisar as suas DMs em massa, com um assistente de IA ou com o seu próprio código, e ver qual mensagem de abertura gera respostas e qual resposta faz um lead superar uma objeção. O Gemlead guarda a sua própria cópia de todas as DMs sincronizada com o X, edições e exclusões incluídas, então o arquivo é criado a partir dessa cópia sem chamar o X e 1 500 conversas ficam prontas em menos de um minuto.

Endpoints

POST/v1/exports
GET/v1/exports
GET/v1/exports/:id

O objeto export

Um arquivo de leads ou de conversas gerado em segundo plano, para os volumes grandes em que a paginação é lenta demais.

Atributos

idstring
Identificador único da exportação.
objectstring
Sempre export.
typestring
O que o arquivo contém, leads ou conversas com as mensagens delas.
leadsconversations
statusstring
processing enquanto o arquivo é gerado, depois ready ou failed. expired quando o link dele expira.
processingreadyfailedexpired
formatstring
O formato do arquivo, csv ou jsonl para leads, jsonl ou markdown para conversas.
csvjsonlmarkdown
filtersobject
Os filtros com que a exportação foi criada, como em Listar leads ou Listar conversas.
row_countinteger
Leads ou conversas no arquivo. O número cresce enquanto o arquivo é gerado. No máximo 100 000 leads ou 20 000 conversas.
total_countinteger ou null
Numa exportação de conversas sem filtros, quantas conversas o arquivo vai ter, contadas quando a geração começa. null nos outros casos.
urlstring ou null
Onde baixar o arquivo, quando ele fica pronto. Funciona por 24 horas, até expires_at.
expires_atstring ou null
Quando a url deixa de funcionar, em ISO 8601.
created_atstring
Quando a exportação foi criada, em ISO 8601.

O objeto export

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Criar uma exportação

POST/v1/exportsScope readMCPcreate_export

Começa a gerar um arquivo de leads ou de conversas. Retorna na hora a exportação em processing.

Parâmetros do corpo

typestring
O que exportar. O padrão é leads.
leadsconversations
formatstring
O formato do arquivo. Para leads, csv ou jsonl, com csv por padrão. Para conversas, jsonl ou markdown, com jsonl por padrão.
csvjsonlmarkdown
filtersobject
Os leads a exportar, com os filtros de Listar leads. Para conversas, só persona e unread, como em Listar conversas.

Retorno

Um objeto export com o status processing e o status HTTP 202.

Erros

400parameter_missing
Falta um parâmetro obrigatório. param diz qual.
400parameter_invalid
Um parâmetro tem um valor que a API não aceita. param diz qual.
429export_rate_limit_exceeded
Mais de 10 exportações na última hora nesta conta.

POST/v1/exports

curl -X POST https://gemlead.ai/api/v1/exports \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": {
      "hot": true,
      "persona": "lvWBPnytpS"
    }
  }'

Resposta202

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "processing",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 0,
  "total_count": null,
  "url": null,
  "expires_at": null,
  "created_at": "2026-11-06T07:45:12.904Z"
}

Listar exportações

GET/v1/exportsScope readMCPlist_exports

Retorna suas exportações, das mais novas para as mais antigas.

Parâmetros de consulta

limitinteger
Quantos objetos retornar, de 1 a 100. O padrão é 25.
cursorstring
O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos export.

GET/v1/exports

curl https://gemlead.ai/api/v1/exports \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Resposta200

{
  "object": "list",
  "data": [
    {
      "id": "e4TnW8yHqA",
      "object": "export",
      "type": "leads",
      "status": "ready",
      "format": "csv",
      "filters": {
        "hot": true,
        "persona": "lvWBPnytpS"
      },
      "row_count": 2134,
      "total_count": null,
      "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
      "expires_at": "2026-11-07T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obter uma exportação

GET/v1/exports/:idScope readMCPget_export

Retorna uma exportação. Consulte a cada poucos segundos até o status ser ready e depois baixe a url.

Parâmetros de caminho

idstringObrigatório
O ID da exportação.

Retorno

Um objeto export.

Erros

404resource_missing
Nenhuma exportação com este ID na conta da chave.

GET/v1/exports/:id

curl https://gemlead.ai/api/v1/exports/e4TnW8yHqA \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Resposta200

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Uma conversa no arquivo

Cada linha de um arquivo jsonl de conversas, da conversa mais recente para a mais antiga. É o objeto conversation com todas as mensagens, o lead e history. Um arquivo markdown traz o mesmo conteúdo, como uma transcrição por conversa.

Atributos

idstring
Identificador único da conversa.
objectstring
Sempre conversation.
lead_idstring
O lead com quem você está falando.
profileobject
O perfil do lead no X, como no objeto lead.
personaobject ou null
A persona do lead.
columnobject ou null
A coluna do seu quadro de Conversas em que a conversa está.
unreadboolean
Indica se a última mensagem do lead ainda não foi lida.
messages_countinteger
Mensagens em messages.
first_message_atstring ou null
Quando a primeira mensagem foi enviada, em ISO 8601.
last_message_atstring ou null
Quando a última mensagem foi enviada, em ISO 8601.
last_messageobject ou null
A última mensagem.
leadobject ou null
O objeto lead, com o score, o status, a persona e a campanha dele.
historystring
complete quando messages traz a conversa inteira. recent enquanto o Gemlead só guarda as últimas mensagens de uma conversa longa, antes de ler o resto no X uma única vez.
completerecent
messagesarray de objects
Todas as mensagens da conversa, das mais antigas para as mais novas, com direção, texto, horário, mídia e reações. Os links de mídia funcionam por 24 horas.

Uma conversa no arquivo

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": false,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 1,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  },
  "first_message_at": "2026-11-06T08:12:44.000Z",
  "lead": {
    "id": "msgOtJ8dvT",
    "object": "lead",
    "profile": {
      "x_user_id": "1460283925",
      "username": "jane_builds",
      "name": "Jane Doe",
      "bio": "Runs a paid trading community. Daily setups, no hype.",
      "followers_count": 12400,
      "following_count": 380,
      "location": "Austin, TX",
      "website": "https://janedoe.com",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
      "verified": true,
      "url": "https://x.com/jane_builds"
    },
    "score": 86,
    "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
    "hot": true,
    "status": "scored",
    "persona": {
      "id": "lvWBPnytpS",
      "name": "Tipsters"
    },
    "campaign": null,
    "conversation_id": null,
    "locked_to": null,
    "found_at": "2026-11-05T14:02:11.482Z",
    "scored_at": "2026-11-05T14:03:40.117Z",
    "updated_at": "2026-11-05T14:03:40.117Z",
    "metadata": {}
  },
  "history": "complete",
  "messages": [
    {
      "id": "1985321409876543210",
      "object": "message",
      "direction": "inbound",
      "text": "Yes, I want to charge for my Discord. How does it work?",
      "created_at": "2026-11-06T08:12:44.000Z",
      "media": [],
      "reactions": [],
      "encrypted": false,
      "reply_to_message_id": null
    }
  ]
}