Skip to main content

Endpoint

GET /v1/ai-agents/runs
Escopo necessário: read:ai_agents Cada vez que um agente atua em uma conversa, gera um run. Use este endpoint para auditar execuções, identificar problemas e acompanhar o desempenho.

Parâmetros de query

ParâmetroTipoDescrição
agent_idstringFiltra por agente
conversation_idstringFiltra por conversa
statusstringFiltra por status do run
started_afterstringISO 8601 — filtra runs iniciados após esta data
limitintegerPadrão 25, máx 100
cursorstringCursor de paginação

Exemplo de requisição

curl "https://api.socialsell.ai/v1/ai-agents/runs?agent_id=664p1q2r3s4t5u6v7w8x9y0z&limit=10" \
  -H "Authorization: Bearer sk_live_..."

Exemplo de resposta

{
  "data": [
    {
      "id": "664q2r3s4t5u6v7w8x9y0z1a",
      "agent": { "id": "664p1q2r3s4t5u6v7w8x9y0z", "name": "Qualificador de Leads", "type": "sales" },
      "conversation_id": "664g2h3i4j5k6l7m8n9o0p1q",
      "trigger_event": "message.received.from_contact",
      "status": "completed",
      "skip_reason": null,
      "messages_sent": [
        { "message_id": "664r...", "content": "Olá! Como posso ajudar?", "sent_at": "2026-06-10T15:00:01.000Z", "delay_ms": 1200 }
      ],
      "handoff": {
        "triggered": true,
        "reason": "customer_requested_human",
        "summary": "Cliente pediu falar com humano sobre contrato."
      },
      "usage": { "tokens": 1850, "cost_cents": 3 },
      "duration_ms": 4200,
      "started_at": "2026-06-10T15:00:00.000Z",
      "completed_at": "2026-06-10T15:00:04.200Z"
    }
  ],
  "meta": { "total": 142, "has_more": true, "next_cursor": "..." }
}

Objeto run

CampoTipoDescrição
idstringID do run
agentobjectAgente {id, name, type}
conversation_idstring|nullConversa onde atuou
trigger_eventstring|nullEvento disparador
statusstringStatus do run
skip_reasonstring|nullMotivo de pulo (se não atuou)
error_messagestring|nullErro, se houver
messages_sentarrayMensagens enviadas pelo agente
handoffobject|nullDetalhes de transferência para humano
usageobject|nullTokens consumidos e custo
duration_msinteger|nullDuração da execução em milissegundos
started_at / completed_atstring|nullTimestamps