Gemlead
Docs
Iniciar sesión
Obtén tu clave API

Referencia de la API

Campañas

Una campaña lleva a los leads calientes de un buyer persona por un flujo de pasos, me gusta, comentarios, follows y DM, todo desde tu cuenta de X, y pasa cada respuesta a tu bandeja de entrada. Crea una a partir de una plantilla o de tu propio flujo, lánzala y sigue sus cifras.

Endpoints

El objeto campaign

Un flujo de prospección que envía DM a los leads calientes de un buyer persona, hace seguimiento y te pasa las respuestas a la bandeja de entrada.

Atributos

  • idstring
    Identificador único de la campaña.
  • objectstring
    Siempre campaign.
  • namestring
    El nombre de la campaña.
  • statusstring
    Si la campaña está enviando.
    draftactivepausedarchived
  • personaobject o null
    El buyer persona cuyos leads entran en la campaña.
  • methodstring o null
    Cómo se encontraron los leads de la campaña. Null en las campañas antiguas.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Los leads con una puntuación inferior nunca entran en la campaña.
  • daily_limitinteger
    El máximo de leads nuevos que entran en la campaña al día, de 5 a 150. Por defecto 60.
  • statsobject
    Totales desde que empezó la campaña. Una respuesta cuenta si llega en los 7 días siguientes al primer DM.
  • created_atstring
    Cuándo se creó la campaña, en ISO 8601.
  • updated_atstring
    Cuándo cambió la campaña por última vez, en ISO 8601.
El 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 campañas

GET/v1/campaignsScope readMCPlist_campaigns

Devuelve tus campañas, primero las más recientes.

Parámetros de consulta

  • statusstring
    Solo las campañas con este estado.
    draftactivepausedarchived
  • personastring
    Solo las campañas del buyer persona con este ID.
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos campaign.

Errores

  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
GET/v1/campaigns
curl -G https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d status=active
Respuesta200
{
  "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
}

Obtener una campaña

GET/v1/campaigns/:idScope read

Devuelve una campaña.

Parámetros de ruta

  • idstringObligatorio
    El ID de la campaña.

Devuelve

Un objeto campaign.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
GET/v1/campaigns/:id
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Crear una campaña

POST/v1/campaignsScope writeMCPcreate_campaign

Crea una campaña en borrador. No se envía nada hasta que la lances. Sin template ni flow, la campaña recibe la plantilla por defecto de la app, el Flujo de calentamiento para B2B y el Flujo instantáneo para B2C.

Parámetros del cuerpo

  • persona_idstringObligatorio
    El buyer persona cuyos leads entran en ella.
  • namestringObligatorio
    El nombre de la campaña, hasta 100 caracteres.
  • methodstring
    Solo entran los leads encontrados de esta forma. Omítelo para incluir todos los leads del buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Solo entran los leads con esta puntuación o más, de 0 a 100. Por defecto 60.
  • daily_limitinteger
    El máximo de leads nuevos que entran al día, de 5 a 150. Por defecto 60. Cada lead nuevo empieza con Radar, que lo añade a una lista privada de X de la cuenta, y por encima de unos cientos al día X bloquea esos añadidos entre 6 y 24 horas.
  • lead_orderstring
    Qué leads entran primero. Por defecto highest, o newest para los métodos de palabras clave y de competidores.
    highestlowestshufflenewest
  • templatestring
    El flujo del que partir. Consulta Listar plantillas de campaña. No se combina con flow.
    warm_upinstantdirect_messageblank
  • flowobject
    Tu propio flujo, en lugar de una plantilla.

Devuelve

El nuevo objeto campaign, con su status en draft.

Errores

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"
  }'
Respuesta200
{
  "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"
}

Lanzar una campaña

POST/v1/campaigns/:campaign_id/startScope writeMCPset_campaign_status

Lanza un borrador o reanuda una campaña en pausa. Los leads entran y los pasos salen desde tu cuenta de X.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

El objeto campaign, con su status en active.

Errores

POST/v1/campaigns/:campaign_id/start
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/start \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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 una campaña

POST/v1/campaigns/:campaign_id/pauseScope writeMCPset_campaign_status

Pausa una campaña. No sale ningún paso nuevo hasta que la vuelvas a lanzar, y los leads conservan su lugar.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

El objeto campaign, con su status en paused.

Errores

POST/v1/campaigns/:campaign_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Archivar una campaña

POST/v1/campaigns/:campaign_id/archiveScope writeMCPset_campaign_status

Termina una campaña definitivamente. Su historial y sus conversaciones se conservan, y Duplicar una campaña permite relanzarla.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

El objeto campaign, con su status en archived.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
POST/v1/campaigns/:campaign_id/archive
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/archive \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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 una campaña

POST/v1/campaigns/:campaign_id/duplicateScope writeMCPduplicate_campaign

Copia los ajustes y el flujo de una campaña, sin sus leads, como un nuevo borrador.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

El nuevo objeto campaign, con su status en draft.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
POST/v1/campaigns/:campaign_id/duplicate
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/duplicate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Eliminar una campaña

DELETE/v1/campaigns/:campaign_idScope writeMCPdelete_campaign

Elimina una campaña. Sus leads y sus conversaciones se conservan. No se puede deshacer.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

Un objeto con el id de la campaña y deleted en true.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
DELETE/v1/campaigns/:campaign_id
curl -X DELETE \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "deleted": true
}

El objeto campaign stats

Los resultados de una campaña en un periodo, en total y día a día.

Atributos

  • objectstring
    Siempre campaign_stats.
  • campaign_idstring
    El ID de la campaña.
  • fromstring
    El primer día, YYYY-MM-DD.
  • tostring
    El último día, YYYY-MM-DD.
  • totalsobject
    leads_added, dms_sent, replies y reply_rate en el periodo.
  • dailyarray de objects
    Una entrada por día con su date, dms_sent y replies.
El 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
    }
  ]
}

Obtener las estadísticas de una campaña

GET/v1/campaigns/:id/statsScope readMCPget_campaign_stats

Devuelve los resultados de una campaña en un periodo, en total y día a día. dms_sent cuenta los primeros DM enviados en el periodo, replies las respuestas de esos leads en los 7 días siguientes. Los días son fechas UTC.

Parámetros de ruta

  • idstringObligatorio
    El ID de la campaña.

Parámetros de consulta

  • fromstring
    El primer día, YYYY-MM-DD. Por defecto, hace 30 días.
  • tostring
    El último día, YYYY-MM-DD. Por defecto, hoy.

Devuelve

Un objeto campaign stats.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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
Respuesta200
{
  "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
    }
  ]
}

El objeto campaign settings

Los ajustes de una campaña y su flujo completo, cada paso con su ID y sus opciones.

Atributos

  • objectstring
    Siempre campaign_settings.
  • campaign_idstring
    El ID de la campaña.
  • persona_idstring o null
    El buyer persona cuyos leads entran en ella.
  • namestring
    El nombre de la campaña.
  • statusstring
    En qué punto está la campaña.
    draftactivepausedarchived
  • methodstring o null
    Solo entran los leads encontrados de esta forma. null deja entrar a todos los leads del buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Solo entran los leads con esta puntuación o más, de 0 a 100.
  • daily_limitinteger
    El máximo de leads nuevos que entran al día, de 5 a 150.
  • lead_orderstring
    Qué leads entran primero. highest la mejor puntuación, lowest la más baja, shuffle al azar o newest los encontrados más recientemente.
    highestlowestshufflenewest
  • flowobject
    Su flujo.
  • updated_atstring
    Cuándo cambió por última vez, en ISO 8601.
El 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"
}

Obtener los ajustes de una campaña

GET/v1/campaigns/:campaign_id/settingsScope readMCPget_campaign_settings

Devuelve los ajustes de una campaña y su flujo, cada paso con su ID y sus opciones. Léelo antes de editar el flujo.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Devuelve

Un objeto campaign settings.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
GET/v1/campaigns/:campaign_id/settings
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Actualizar los ajustes de una campaña

PATCH/v1/campaigns/:campaign_id/settingsScope writeMCPupdate_campaign

Cambia los ajustes que envías y conserva los demás. Un flow reemplaza el flujo entero, incluso en una campaña en curso. Conserva los ID de los pasos que mantienes, así los leads que esperan en ellos se quedan ahí, y la app mueve a los demás.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Parámetros del cuerpo

  • namestring
    El nombre de la campaña, hasta 100 caracteres.
  • methodstring o null
    Solo entran los leads encontrados de esta forma, null para todos los leads del buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Solo entran los leads con esta puntuación o más, de 0 a 100.
  • daily_limitinteger
    El máximo de leads nuevos que entran al día, de 5 a 150.
  • lead_orderstring
    Qué leads entran primero. highest la mejor puntuación, lowest la más baja, shuffle al azar o newest los encontrados más recientemente.
    highestlowestshufflenewest
  • flowobject
    El nuevo flujo, completo.

Devuelve

El objeto campaign settings actualizado.

Errores

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
  }'
Respuesta200
{
  "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"
}

El objeto flow

Los pasos que una campaña ejecuta para cada lead, en orden. Una bifurcación ejecuta if_yes o if_no y luego los pasos que la siguen. Un flujo tiene 60 pasos como máximo, las bifurcaciones admiten 2 niveles y los ID de paso son únicos. Un paso solo acepta las opciones de su tipo. Cada me gusta, comentario, follow y DM sale de tu cuenta de X. El lienzo de la app muestra el flujo igual que sus propias plantillas.

Atributos

  • stepsarray de objectsObligatorio
    Los pasos, en orden.
El 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
    }
  ]
}

El objeto campaign lead

Un lead en una campaña, el paso en el que está y lo que la campaña publicó para él.

Atributos

  • objectstring
    Siempre campaign_lead.
  • idstring o null
    Identificador único del recorrido del lead en esta campaña.
  • campaign_idstring
    El ID de la campaña.
  • lead_idstring o null
    El ID del lead.
  • statusstring
    El estado del lead en la campaña, como waiting, replied, completed o failed.
  • stepstring o null
    La etiqueta del paso en el que está.
  • entered_atstring o null
    Cuándo entró en la campaña, en ISO 8601.
  • leadobject o null
    El lead.
  • postedobject
    Lo que se envió a este lead.
El 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 los leads de una campaña

GET/v1/campaigns/:campaign_id/leadsScope readMCPlist_campaign_leads

Devuelve los leads de una campaña según dónde están en el flujo, con lo que la campaña publicó para cada uno.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Parámetros de consulta

  • stagestring
    all son todos los leads que entraron. step, los que pasaron el paso step_id, y fork, los que tomaron una de sus ramas. dm_sent, replied, finished para los completados o que respondieron, completed para los que hicieron todos los pasos sin responder. Por defecto all.
    allstepforkdm_sentrepliedfinishedcompleted
  • step_idstring
    Con step o fork, el ID del paso.
  • branchstring
    Con fork, la rama.
    yesno
  • skippedboolean
    Con step en un paso de comentario o de DM, los leads para los que no publicó nada.
  • qstring
    Busca por nombre o por nombre de usuario.
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos campaign lead, con total_count.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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
Respuesta200
{
  "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
}

El objeto campaign trends

La actividad de una campaña por día durante 14 días o por hora durante 24 horas, como en su gráfico de la app.

Atributos

  • objectstring
    Siempre campaign_trends.
  • campaign_idstring
    El ID de la campaña.
  • rangestring
    El periodo.
    14d24h
  • timezonestring
    La zona horaria de los tramos.
  • bucketsarray de objects
    Uno por día o por hora, cada uno con su key y las métricas pedidas.
  • totalsobject
    Desde que empezó la campaña, sus started, sent, replies y follows, con last_sent_at y last_reply_at.
  • truncatedboolean
    true si la campaña es demasiado grande para contarla entera.
  • generated_atstring
    Cuándo se leyeron las cifras, en ISO 8601.
El 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"
}

Obtener las tendencias de una campaña

GET/v1/campaigns/:campaign_id/trendsScope readMCPget_campaign_trends

Devuelve los leads iniciados, los DM enviados, las respuestas y los follows de una campaña por día durante 14 días, o por hora durante 24 horas.

Parámetros de ruta

  • campaign_idstringObligatorio
    El ID de la campaña.

Parámetros de consulta

  • metricsstring
    Cualquiera de started, sent, replies y follows, separadas por comas. Por defecto, las cuatro.
    startedsentrepliesfollows
  • rangestring
    14d por día, 24h por hora. Por defecto 14d.
    14d24h
  • timezonestring
    La zona horaria IANA de los tramos, como Europe/Paris. Por defecto UTC.

Devuelve

Un objeto campaign trends.

Errores

  • 404resource_missing
    No hay ninguna campaña con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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"
Respuesta200
{
  "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"
}

El objeto campaign template

Un flujo del que partir para una campaña, tal como lo ofrece la app. El flujo de cada plantilla es un flujo válido para Crear una campaña.

Atributos

  • objectstring
    Siempre campaign_template.
  • idstring
    El ID de la plantilla, para el parámetro template.
    warm_upinstantdirect_messageblank
  • descriptionstring
    Lo que hace el flujo, en pocas frases.
  • defaultboolean
    Si la app la elige para este método y este mercado.
  • flowobject
    Su flujo.
El 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 plantillas de campaña

GET/v1/campaign_templatesScope readMCPlist_campaign_templates

Devuelve las plantillas de la app con sus flujos completos, la mejor referencia para cada tipo de paso y cada opción. El Flujo de calentamiento da me gusta, comenta y sigue antes del DM. El Flujo instantáneo lo hace todo de golpe y envía el DM un día después. Mensaje directo solo envía el DM.

Parámetros de consulta

  • methodstring
    El método de la campaña. El Flujo instantáneo cambia según él.
    followingkeywordscompetitor_followerscompetitor_comments
  • marketstring
    El mercado del buyer persona. En b2c, Mensaje directo envía al instante, sin Radar.
    b2bb2c

Devuelve

Una lista de objetos campaign template.

Errores

  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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
Respuesta200
{
  "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
}
Recibe las novedades de Gemlead
directamente en tu bandeja de entrada.
Suscribirme
Al suscribirte aceptas nuestra Política de privacidad y das tu consentimiento para recibir novedades de nuestra empresa.
Gemlead
Producto
Empezar
Iniciar sesión
Para quién
Agentes de IA
Funciones
Precios
Afiliados
FAQ
Funciones
Compradores 24/7Primero los calientes+60% de respuestasDM a medidaUna bandeja para todoTu closer con IAEscala sin límitesAPI, MCP, webhooksPregunta a Gemlead
Recursos
InicioAPIBlog
Legal
Términos
Privacidad
© 2026 Gemlead, Inc. Todos los derechos reservados.
Español