Gemlead
Docs
Entrar
Obter sua chave de API

Referência da API

Campanhas

Uma campanha conduz os leads quentes de uma persona por um fluxo de etapas, curtidas, comentários, follows e DMs, tudo pela sua conta do X, e envia cada resposta para a sua inbox. Crie uma a partir de um modelo ou do seu próprio fluxo, inicie e acompanhe os números.

Endpoints

O objeto campaign

Um fluxo de prospecção que manda DMs para os leads quentes de uma persona, faz o follow-up e entrega as respostas na sua inbox.

Atributos

  • idstring
    Identificador único da campanha.
  • objectstring
    Sempre campaign.
  • namestring
    O nome da campanha.
  • statusstring
    Indica se a campanha está enviando.
    draftactivepausedarchived
  • personaobject ou null
    A persona cujos leads entram na campanha.
  • methodstring ou null
    Como os leads da campanha foram encontrados. Null nas campanhas mais antigas.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Leads com score menor nunca entram na campanha.
  • daily_limitinteger
    O máximo de leads novos que entram na campanha por dia, de 5 a 150. O padrão é 60.
  • statsobject
    Os totais desde o início da campanha. Uma resposta conta quando chega até 7 dias depois da primeira DM.
  • created_atstring
    Quando a campanha foi criada, em ISO 8601.
  • updated_atstring
    Quando a campanha mudou pela última vez, em ISO 8601.
O objeto campaign
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Listar campanhas

GET/v1/campaignsScope readMCPlist_campaigns

Retorna suas campanhas, das mais novas para as mais antigas.

Parâmetros de consulta

  • statusstring
    Só as campanhas com este status.
    draftactivepausedarchived
  • personastring
    Só as campanhas da persona com este ID.
  • 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 campaign.

Erros

  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
GET/v1/campaigns
curl -G https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d status=active
Resposta200
{
  "object": "list",
  "data": [
    {
      "id": "c7RkQ2wLxe",
      "object": "campaign",
      "name": "Tipsters warm intro",
      "status": "active",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "method": "keywords",
      "min_score": 60,
      "daily_limit": 50,
      "stats": {
        "leads": 640,
        "dms_sent": 412,
        "replies": 57,
        "reply_rate": 13.8
      },
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obter uma campanha

GET/v1/campaigns/:idScope read

Retorna uma campanha.

Parâmetros de caminho

  • idstringObrigatório
    O ID da campanha.

Retorno

Um objeto campaign.

Erros

GET/v1/campaigns/:id
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Criar uma campanha

POST/v1/campaignsScope writeMCPcreate_campaign

Cria uma campanha como rascunho. Nada é enviado até você iniciar a campanha. Sem template nem flow, a campanha recebe o padrão do app, o Fluxo de aquecimento para B2B e o Fluxo instantâneo para B2C.

Parâmetros do corpo

  • persona_idstringObrigatório
    A persona cujos leads entram nela.
  • namestringObrigatório
    O nome da campanha, com até 100 caracteres.
  • methodstring
    Só entram os leads encontrados desta forma. Omita para incluir todos os leads da persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Só entram os leads com pelo menos este score, de 0 a 100. O padrão é 60.
  • daily_limitinteger
    O máximo de leads novos que entram por dia, de 5 a 150. O padrão é 60. Cada lead novo começa pelo Radar, que o adiciona a uma lista privada do X da conta, e o X bloqueia essas adições por 6 a 24 horas acima de algumas centenas por dia.
  • lead_orderstring
    Quais leads entram primeiro. O padrão é highest, ou newest para os métodos de palavra-chave e de concorrentes.
    highestlowestshufflenewest
  • templatestring
    O fluxo de partida. Veja Listar modelos de campanha. Não pode ser usado com flow.
    warm_upinstantdirect_messageblank
  • flowobject
    O seu próprio fluxo, no lugar de um modelo.

Retorno

O novo objeto campaign, com o status em draft.

Erros

POST/v1/campaigns
curl -X POST https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": "lvWBPnytpS",
    "name": "Tipsters warm intro",
    "method": "keywords",
    "daily_limit": 50,
    "template": "instant"
  }'
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "draft",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 0,
    "dms_sent": 0,
    "replies": 0,
    "reply_rate": null
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Iniciar uma campanha

POST/v1/campaigns/:campaign_id/startScope writeMCPset_campaign_status

Inicia um rascunho ou retoma uma campanha pausada. Os leads começam a entrar e as etapas são executadas pela sua conta do X.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

O objeto campaign, com o status em active.

Erros

POST/v1/campaigns/:campaign_id/start
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/start \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Pausar uma campanha

POST/v1/campaigns/:campaign_id/pauseScope writeMCPset_campaign_status

Pausa uma campanha. Nenhuma etapa nova é executada até você iniciar a campanha de novo, e os leads mantêm a posição deles.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

O objeto campaign, com o status em paused.

Erros

POST/v1/campaigns/:campaign_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "paused",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Arquivar uma campanha

POST/v1/campaigns/:campaign_id/archiveScope writeMCPset_campaign_status

Encerra uma campanha de vez. O histórico e as conversas dela continuam, e Duplicar uma campanha permite rodá-la de novo.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

O objeto campaign, com o status em archived.

Erros

POST/v1/campaigns/:campaign_id/archive
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/archive \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "archived",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Duplicar uma campanha

POST/v1/campaigns/:campaign_id/duplicateScope writeMCPduplicate_campaign

Copia as configurações e o fluxo de uma campanha, sem os leads dela, como um novo rascunho.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

O novo objeto campaign, com o status em draft.

Erros

POST/v1/campaigns/:campaign_id/duplicate
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/duplicate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c2VbN6mQrz",
  "object": "campaign",
  "name": "Tipsters warm intro copy",
  "status": "draft",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 0,
    "dms_sent": 0,
    "replies": 0,
    "reply_rate": null
  },
  "created_at": "2026-11-06T07:45:12.904Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Excluir uma campanha

DELETE/v1/campaigns/:campaign_idScope writeMCPdelete_campaign

Exclui uma campanha. Os leads e as conversas deles continuam. Essa ação não pode ser desfeita.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

Um objeto com o id da campanha e deleted igual a true.

Erros

DELETE/v1/campaigns/:campaign_id
curl -X DELETE \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "deleted": true
}

O objeto campaign stats

Os resultados de uma campanha num período, no total e dia a dia.

Atributos

  • objectstring
    Sempre campaign_stats.
  • campaign_idstring
    O ID da campanha.
  • fromstring
    O primeiro dia, YYYY-MM-DD.
  • tostring
    O último dia, YYYY-MM-DD.
  • totalsobject
    leads_added, dms_sent, replies e reply_rate no período.
  • dailyarray de objects
    Uma entrada por dia com date, dms_sent e replies.
O objeto campaign stats
{
  "object": "campaign_stats",
  "campaign_id": "c7RkQ2wLxe",
  "from": "2026-10-08",
  "to": "2026-11-06",
  "totals": {
    "leads_added": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "daily": [
    {
      "date": "2026-11-04",
      "dms_sent": 22,
      "replies": 3
    },
    {
      "date": "2026-11-05",
      "dms_sent": 25,
      "replies": 4
    },
    {
      "date": "2026-11-06",
      "dms_sent": 9,
      "replies": 1
    }
  ]
}

Obter as estatísticas de uma campanha

GET/v1/campaigns/:id/statsScope readMCPget_campaign_stats

Retorna os resultados de uma campanha num período, no total e dia a dia. dms_sent conta as primeiras DMs enviadas no período, replies as respostas desses leads em até 7 dias. Os dias são datas em UTC.

Parâmetros de caminho

  • idstringObrigatório
    O ID da campanha.

Parâmetros de consulta

  • fromstring
    O primeiro dia, YYYY-MM-DD. O padrão é 30 dias atrás.
  • tostring
    O último dia, YYYY-MM-DD. O padrão é hoje.

Retorno

Um objeto campaign stats.

Erros

GET/v1/campaigns/:id/stats
curl -G https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/stats \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d from=2026-10-08 \
  -d to=2026-11-06
Resposta200
{
  "object": "campaign_stats",
  "campaign_id": "c7RkQ2wLxe",
  "from": "2026-10-08",
  "to": "2026-11-06",
  "totals": {
    "leads_added": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "daily": [
    {
      "date": "2026-11-04",
      "dms_sent": 22,
      "replies": 3
    },
    {
      "date": "2026-11-05",
      "dms_sent": 25,
      "replies": 4
    },
    {
      "date": "2026-11-06",
      "dms_sent": 9,
      "replies": 1
    }
  ]
}

O objeto campaign settings

As configurações e o fluxo completo de uma campanha, cada etapa com o seu ID e as suas opções.

Atributos

  • objectstring
    Sempre campaign_settings.
  • campaign_idstring
    O ID da campanha.
  • persona_idstring ou null
    A persona cujos leads entram nela.
  • namestring
    O nome da campanha.
  • statusstring
    Em que ponto está a campanha.
    draftactivepausedarchived
  • methodstring ou null
    Só entram os leads encontrados desta forma. null deixa entrar todos os leads da persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Só entram os leads com pelo menos este score, de 0 a 100.
  • daily_limitinteger
    O máximo de leads novos que entram por dia, de 5 a 150.
  • lead_orderstring
    Quais leads entram primeiro. highest pelo maior score, lowest pelo menor, shuffle em ordem aleatória ou newest pelos encontrados mais recentemente.
    highestlowestshufflenewest
  • flowobject
    O fluxo dela.
  • updated_atstring
    Quando ela mudou pela última vez, em ISO 8601.
O objeto campaign settings
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Obter as configurações de uma campanha

GET/v1/campaigns/:campaign_id/settingsScope readMCPget_campaign_settings

Retorna as configurações e o fluxo de uma campanha, cada etapa com o seu ID e as suas opções. Leia antes de editar o fluxo.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Retorno

Um objeto campaign settings.

Erros

GET/v1/campaigns/:campaign_id/settings
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Atualizar as configurações de uma campanha

PATCH/v1/campaigns/:campaign_id/settingsScope writeMCPupdate_campaign

Altera as configurações que você envia e mantém as outras. Um flow substitui o fluxo inteiro, mesmo numa campanha ativa. Mantenha os IDs das etapas que você conservar, assim os leads que esperam nelas continuam ali, e o app move os outros.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Parâmetros do corpo

  • namestring
    O nome da campanha, com até 100 caracteres.
  • methodstring ou null
    Só entram os leads encontrados desta forma, null para todos os leads da persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Só entram os leads com pelo menos este score, de 0 a 100.
  • daily_limitinteger
    O máximo de leads novos que entram por dia, de 5 a 150.
  • lead_orderstring
    Quais leads entram primeiro. highest pelo maior score, lowest pelo menor, shuffle em ordem aleatória ou newest pelos encontrados mais recentemente.
    highestlowestshufflenewest
  • flowobject
    O novo fluxo, completo.

Retorno

O objeto campaign settings atualizado.

Erros

PATCH/v1/campaigns/:campaign_id/settings
curl -X PATCH \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_limit": 80,
    "min_score": 70
  }'
Resposta200
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 70,
  "daily_limit": 80,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

O objeto flow

As etapas que uma campanha executa para cada lead, em ordem. Uma bifurcação executa if_yes ou if_no e depois as etapas seguintes. Um fluxo tem no máximo 60 etapas, as bifurcações vão até 2 níveis e os IDs das etapas são únicos. Uma etapa só aceita as opções do seu tipo. Toda curtida, comentário, follow e DM sai da sua conta do X. O canvas do app organiza o fluxo do mesmo jeito que os próprios modelos.

Atributos

  • stepsarray de objectsObrigatório
    As etapas, em ordem.
O objeto flow
{
  "steps": [
    {
      "id": "in-like",
      "type": "like",
      "label": "Like",
      "count": 1
    },
    {
      "id": "in-follow",
      "type": "follow",
      "label": "Follow"
    },
    {
      "id": "in-timer",
      "type": "timer",
      "label": "Timer",
      "duration": "1d"
    },
    {
      "id": "in-inbox",
      "type": "can_dm",
      "label": "Inbox opened test",
      "if_yes": [
        {
          "id": "in-dm",
          "type": "send_dm",
          "label": "Direct message",
          "mode": "ai",
          "dm_kind": "cold",
          "language": "auto",
          "instructions": null,
          "template": null
        },
        {
          "id": "in-comment-bridge",
          "type": "comment",
          "label": "Comment",
          "comment_type": "bridge",
          "language": "auto",
          "instructions": null
        }
      ],
      "if_no": [
        {
          "id": "in-comment-closed",
          "type": "comment",
          "label": "Comment",
          "comment_type": "inbox_closed",
          "language": "auto",
          "instructions": null
        }
      ]
    },
    {
      "id": "in-timer-followup",
      "type": "timer",
      "label": "Timer",
      "duration": "3d"
    },
    {
      "id": "in-dm-followup",
      "type": "send_dm",
      "label": "Direct message",
      "mode": "ai",
      "dm_kind": "follow_up",
      "language": "auto",
      "instructions": null,
      "template": null
    },
    {
      "id": "in-cleaner",
      "type": "cleaner",
      "label": "Cleaner",
      "unfollow": true,
      "delete_comments": true,
      "delete_likes": true
    }
  ]
}

O objeto campaign lead

Um lead numa campanha, a etapa em que ele está e o que a campanha publicou para ele.

Atributos

  • objectstring
    Sempre campaign_lead.
  • idstring ou null
    Identificador único da passagem do lead por esta campanha.
  • campaign_idstring
    O ID da campanha.
  • lead_idstring ou null
    O ID do lead.
  • statusstring
    O status do lead na campanha, como waiting, replied, completed ou failed.
  • stepstring ou null
    O nome da etapa em que ele está.
  • entered_atstring ou null
    Quando ele entrou na campanha, em ISO 8601.
  • leadobject ou null
    O lead.
  • postedobject
    O que foi enviado para este lead.
O objeto campaign lead
{
  "object": "campaign_lead",
  "id": "cl9TzQ4wKa",
  "campaign_id": "c7RkQ2wLxe",
  "lead_id": "msgOtJ8dvT",
  "status": "replied",
  "step": "Direct message",
  "entered_at": "2026-11-05T15:00:08.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": {}
  },
  "posted": {
    "comments": [],
    "dms": [
      {
        "text": "Hey Jane, saw you want a real checkout for your picks. Want to see how others charge for their Discord?",
        "message_id": "1985300011122233344",
        "at": "2026-11-06T07:58:21.000Z"
      }
    ]
  }
}

Listar os leads de uma campanha

GET/v1/campaigns/:campaign_id/leadsScope readMCPlist_campaign_leads

Retorna os leads de uma campanha conforme o ponto em que estão no fluxo, com o que a campanha publicou para cada um.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Parâmetros de consulta

  • stagestring
    all são todos os leads que entraram. step são os que passaram pela etapa step_id, fork os que seguiram um dos ramos dela. dm_sent, replied, finished para os concluídos ou que responderam, completed para os que fizeram todas as etapas sem responder. O padrão é all.
    allstepforkdm_sentrepliedfinishedcompleted
  • step_idstring
    Com step ou fork, o ID da etapa.
  • branchstring
    Com fork, o ramo.
    yesno
  • skippedboolean
    Com step numa etapa de comentário ou de DM, os leads para os quais ela não publicou nada.
  • qstring
    Busca por nome ou username.
  • 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 campaign lead, com total_count.

Erros

GET/v1/campaigns/:campaign_id/leads
curl -G https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d stage=replied
Resposta200
{
  "object": "list",
  "data": [
    {
      "object": "campaign_lead",
      "id": "cl9TzQ4wKa",
      "campaign_id": "c7RkQ2wLxe",
      "lead_id": "msgOtJ8dvT",
      "status": "replied",
      "step": "Direct message",
      "entered_at": "2026-11-05T15:00:08.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": {}
      },
      "posted": {
        "comments": [],
        "dms": [
          {
            "text": "Hey Jane, saw you want a real checkout for your picks. Want to see how others charge for their Discord?",
            "message_id": "1985300011122233344",
            "at": "2026-11-06T07:58:21.000Z"
          }
        ]
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0",
  "total_count": 57
}

O objeto campaign trends

A atividade de uma campanha por dia em 14 dias ou por hora em 24 horas, como no gráfico dela no app.

Atributos

  • objectstring
    Sempre campaign_trends.
  • campaign_idstring
    O ID da campanha.
  • rangestring
    O período.
    14d24h
  • timezonestring
    O fuso horário dos intervalos.
  • bucketsarray de objects
    Um por dia ou por hora, cada um com a sua key e as métricas solicitadas.
  • totalsobject
    Desde o início da campanha, os started, sent, replies e follows dela, com last_sent_at e last_reply_at.
  • truncatedboolean
    true quando a campanha é grande demais para ser contada por inteiro.
  • generated_atstring
    Quando os números foram lidos, em ISO 8601.
O objeto campaign trends
{
  "object": "campaign_trends",
  "campaign_id": "c7RkQ2wLxe",
  "range": "14d",
  "timezone": "Europe/Paris",
  "buckets": [
    {
      "key": "2026-11-04",
      "started": 48,
      "sent": 22,
      "replies": 3,
      "follows": 9
    },
    {
      "key": "2026-11-05",
      "started": 50,
      "sent": 25,
      "replies": 4,
      "follows": 11
    },
    {
      "key": "2026-11-06",
      "started": 21,
      "sent": 9,
      "replies": 1,
      "follows": 4
    }
  ],
  "totals": {
    "started": 640,
    "sent": 412,
    "replies": 57,
    "follows": 133,
    "last_sent_at": "2026-11-06T08:20:03.000Z",
    "last_reply_at": "2026-11-06T08:12:44.000Z"
  },
  "truncated": false,
  "generated_at": "2026-11-06T08:30:00.000Z"
}

Obter as tendências de uma campanha

GET/v1/campaigns/:campaign_id/trendsScope readMCPget_campaign_trends

Retorna os leads iniciados, as DMs enviadas, as respostas e os follows de uma campanha por dia em 14 dias, ou por hora em 24 horas.

Parâmetros de caminho

  • campaign_idstringObrigatório
    O ID da campanha.

Parâmetros de consulta

  • metricsstring
    Qualquer um entre started, sent, replies e follows, separados por vírgula. O padrão são os quatro.
    startedsentrepliesfollows
  • rangestring
    14d por dia, 24h por hora. O padrão é 14d.
    14d24h
  • timezonestring
    O fuso horário IANA dos intervalos, como Europe/Paris. O padrão é UTC.

Retorno

Um objeto campaign trends.

Erros

GET/v1/campaigns/:campaign_id/trends
curl -G \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/trends \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d range=14d \
  --data-urlencode "timezone=Europe/Paris"
Resposta200
{
  "object": "campaign_trends",
  "campaign_id": "c7RkQ2wLxe",
  "range": "14d",
  "timezone": "Europe/Paris",
  "buckets": [
    {
      "key": "2026-11-04",
      "started": 48,
      "sent": 22,
      "replies": 3,
      "follows": 9
    },
    {
      "key": "2026-11-05",
      "started": 50,
      "sent": 25,
      "replies": 4,
      "follows": 11
    },
    {
      "key": "2026-11-06",
      "started": 21,
      "sent": 9,
      "replies": 1,
      "follows": 4
    }
  ],
  "totals": {
    "started": 640,
    "sent": 412,
    "replies": 57,
    "follows": 133,
    "last_sent_at": "2026-11-06T08:20:03.000Z",
    "last_reply_at": "2026-11-06T08:12:44.000Z"
  },
  "truncated": false,
  "generated_at": "2026-11-06T08:30:00.000Z"
}

O objeto campaign template

Um fluxo de partida para uma campanha, como o app oferece. O fluxo de cada modelo é válido para Criar uma campanha.

Atributos

  • objectstring
    Sempre campaign_template.
  • idstring
    O ID do modelo, para o parâmetro template.
    warm_upinstantdirect_messageblank
  • descriptionstring
    O que o fluxo faz, em poucas frases.
  • defaultboolean
    Indica se o app escolhe este modelo para esse método e esse mercado.
  • flowobject
    O fluxo dela.
O objeto campaign template
{
  "object": "campaign_template",
  "id": "direct_message",
  "description": "Radar waits until they are online, then the message. No warm up.",
  "default": false,
  "flow": {
    "steps": [
      {
        "id": "dm-snapshot",
        "type": "snapshot",
        "label": "Radar"
      },
      {
        "id": "dm-send",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "cold",
        "language": "auto",
        "instructions": null,
        "template": null
      }
    ]
  }
}

Listar modelos de campanha

GET/v1/campaign_templatesScope readMCPlist_campaign_templates

Retorna os modelos do app com os fluxos completos, a melhor referência para cada tipo de etapa e cada opção. O Fluxo de aquecimento curte, comenta e segue antes da DM. O Fluxo instantâneo faz tudo de uma vez e manda a DM um dia depois. O modelo Mensagem direta só envia a DM.

Parâmetros de consulta

  • methodstring
    O método da campanha. O Fluxo instantâneo varia conforme o método.
    followingkeywordscompetitor_followerscompetitor_comments
  • marketstring
    O mercado da persona. Em b2c, o modelo Mensagem direta envia na hora, sem o Radar.
    b2bb2c

Retorno

Uma lista de objetos campaign template.

Erros

  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
GET/v1/campaign_templates
curl -G https://gemlead.ai/api/v1/campaign_templates \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d method=following \
  -d market=b2b
Resposta200
{
  "object": "list",
  "data": [
    {
      "object": "campaign_template",
      "id": "direct_message",
      "description": "Radar waits until they are online, then the message. No warm up.",
      "default": false,
      "flow": {
        "steps": [
          {
            "id": "dm-snapshot",
            "type": "snapshot",
            "label": "Radar"
          },
          {
            "id": "dm-send",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          }
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Receba as novidades do Gemlead
direto no seu e-mail.
Assinar
Ao assinar, você aceita a nossa Política de Privacidade e concorda em receber novidades da nossa empresa.
Gemlead
Produto
Começar
Entrar
Para quem
Agentes de IA
Recursos
Preços
Afiliados
FAQ
Recursos
Compradores, 24/7Os quentes primeiro+60% de respostasDMs sob medidaTudo numa caixa sóSeu closer de IAEscale sem limitesAPI, MCP, webhooksPergunte ao Gemlead
Conteúdo
InícioAPIBlog
Jurídico
Termos
Privacidade
© 2026 Gemlead, Inc. Todos os direitos reservados.
Português