Campaigns

Una campaign representa una ejecución masiva basada en un CSV. El procesamiento es asíncrono: la creación responde de inmediato y el estado avanza por su cuenta.

Estados

Estado	Significado
`PENDING`	Aceptada, todavía sin marcar
`PROCESSING`	Marcando contactos
`RETRYING`	Reintentando los contactos que no se lograron
`PAUSED`	Detenida a petición; sus contactos siguen vivos y se reanudan
`COMPLETED`	Terminó y todos los contactos se resolvieron
`PARTIALLY_COMPLETED`	Terminó con contactos sin resolver
`FAILED`	Terminó sin poder ejecutarse
`CANCELLED`	Cancelada; no marcará a nadie más

PENDING, PROCESSING y RETRYING son los estados en los que la campaña puede marcar ahora mismo. COMPLETED, PARTIALLY_COMPLETED, FAILED y CANCELLED son terminales. PAUSED no es terminal: se reanuda.

Requiere permisos campaigns:read para consultas y campaigns:write para creación, además del header X-Workspace-Id.

Listar campañas

TypeScript SDK
cURL

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
});

const page1 = await client.campaigns.list({
  page: 1,
  limit: 20,
  sort: "-createdAt",
  // filter: 'and(eq(status,"PROCESSING"))',
});

console.log(page1.data.length, page1.meta.total);

if (page1.meta.hasNext) {
  const page2 = await page1.next();
  console.log("Siguiente página:", page2?.meta.page);
}

curl -sS "$API_BASE_URL/v1/campaigns?page=1&limit=20&sort=-createdAt" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

TypeScript SDK
cURL

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
});

const campaign = await client.campaigns.get(
  "00000000-0000-4000-8000-000000000001",
);

console.log(campaign.name, campaign.status);

curl -sS "$API_BASE_URL/v1/campaigns/00000000-0000-4000-8000-000000000001" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Listar ejecuciones (por fila)

Expone progreso fila por fila del CSV procesado.

TypeScript SDK
cURL

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
});

const executions = await client.campaigns.listExecutions(
  "00000000-0000-4000-8000-000000000001",
  { page: 1, limit: 50 },
);

for (const row of executions.data) {
  console.log(row.rowNumber, row.status, row.error);
}

curl -sS "$API_BASE_URL/v1/campaigns/00000000-0000-4000-8000-000000000001/executions?page=1&limit=50" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Crear campaña (CSV)

Crea una campaña para una versión específica del agente.

TypeScript SDK
cURL

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
});

const campaign = await client.campaigns.create(
  "00000000-0000-4000-8000-000000000101",
  "00000000-0000-4000-8000-000000000201",
  {
    name: "Campaña outbound noviembre",
    objective: "Validar rendimiento de script de retención",
    // En entornos browser: File/Blob.
    // En entornos Node: usa FormData directamente si no tienes File.
    file: new Blob(["name,phone\nAda,+5215555555555\n"], {
      type: "text/csv",
    }),
  },
);

console.log(campaign.campaignId, campaign.status);

curl -sS -X POST \
  "$API_BASE_URL/v1/agents/00000000-0000-4000-8000-000000000101/versions/00000000-0000-4000-8000-000000000201/campaigns" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -F "name=Campaña outbound noviembre" \
  -F "objective=Validar rendimiento de script de retención" \
  -F "file=@./input.csv"

Controlar una campaña en curso

Los tres endpoints requieren el scope campaigns:write y responden 200 con el estado resultante.

curl -sS -X POST "$API_BASE_URL/v1/campaigns/$CAMPAIGN_ID/pause" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

# → { "status": "paused" }

curl -sS -X POST "$API_BASE_URL/v1/campaigns/$CAMPAIGN_ID/resume" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

# → { "status": "resumed" }

curl -sS -X POST "$API_BASE_URL/v1/campaigns/$CAMPAIGN_ID/cancel" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

# → { "status": "cancelled" }

Pausar detiene el marcado pero no cancela la campaña: sus contactos siguen vivos y se retoman al reanudar. Cancelar es terminal — no hay vuelta atrás, y los contactos que quedaban sin marcar no se marcan.

Exportar las ejecuciones a CSV

Devuelve el archivo directamente (text/csv, con Content-Disposition: attachment), no un enlace. Requiere el scope campaigns:read.

curl -sS "$API_BASE_URL/v1/campaigns/$CAMPAIGN_ID/executions/export" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -o ejecuciones.csv

La exportación se genera de forma síncrona mientras la petición está abierta. Para campañas grandes conviene consumirla desde un proceso con un timeout holgado, no desde una petición de navegador.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

Estados

Listar campañas

Listar ejecuciones (por fila)

Crear campaña (CSV)

Controlar una campaña en curso

Exportar las ejecuciones a CSV

​Estados

​Listar campañas

​Listar ejecuciones (por fila)

​Crear campaña (CSV)

​Controlar una campaña en curso

​Exportar las ejecuciones a CSV

Estados

Listar campañas

Listar ejecuciones (por fila)

Crear campaña (CSV)

Controlar una campaña en curso

Exportar las ejecuciones a CSV