> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Executar agents via API

> Crie um run, acompanhe o status e colete a resposta do agent

Um **run** é uma unidade de trabalho do agent iniciada pelo seu sistema: você envia uma instrução, o agent a executa, e o run carrega o status e o resultado. Esta página percorre o ciclo completo — criar, consultar, coletar, cancelar.

## Antes de começar

* Um token de API com modo `read_write`, criado em **Settings → API tokens** ([autenticação](/pt-BR/api/overview#autenticação)).
* O ID do agent, visível na página do agent no dashboard.

## Criar um run

Envie a instrução em `input.message`. Se o run reage a um evento, coloque o payload do evento em `input.data` — o agent o recebe como dados, nunca como instruções.

```bash theme={null}
curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-4821" \
  -d '{
    "input": {
      "message": "Qualifique este lead e responda com um resumo curto.",
      "data": { "leadId": "4821", "origem": "landing-page" }
    },
    "metadata": { "leadId": "4821" }
  }'
```

<ParamField body="input.message" type="string" required>
  A instrução para o agent. Até 128 KiB.
</ParamField>

<ParamField body="input.data" type="object">
  JSON livre com dados do evento, até 128 KiB. Chega ao agent demarcado como
  dado não confiável — use para payloads vindos do mundo externo.
</ParamField>

<ParamField body="metadata" type="object">
  Até 16 chaves de texto (valores de até 512 caracteres). Devolvido no run e
  nos webhooks — use para correlacionar com registros do seu sistema.
</ParamField>

<ParamField body="sessionId" type="string">
  Continua uma sessão de API existente deste agent em vez de iniciar uma nova
  conversa. Runs na mesma sessão são processados em ordem.
</ParamField>

<ParamField body="callbackUrl" type="string">
  URL HTTPS notificada quando o run termina. Veja
  [Webhooks de conclusão](/pt-BR/api/webhooks).
</ParamField>

<ParamField body="title" type="string">
  Título opcional para a nova sessão, exibido no dashboard.
</ParamField>

A resposta é `202 Accepted` com o recurso do run:

```json theme={null}
{
  "id": "run_id",
  "object": "agent.run",
  "agentId": "agent_id",
  "sessionId": "session_id",
  "status": "queued",
  "statusDetail": null,
  "origin": "api",
  "input": { "message": "Qualifique este lead e responda com um resumo curto." },
  "output": null,
  "error": null,
  "metadata": { "leadId": "4821" },
  "createdAt": 1720000000000,
  "completedAt": null,
  "urls": { "self": "/api/v1/runs/run_id" }
}
```

<Note>
  Envie sempre um `Idempotency-Key`. Se a requisição for repetida, você recebe
  o run original de volta em vez de um duplicado. Detalhes na
  [visão geral da API](/pt-BR/api/overview#idempotência).
</Note>

## Acompanhar o run

Consulte a URL de `urls.self` até o status ser terminal:

```bash theme={null}
curl https://app.leme.ai/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer leme_pat_v1_..."
```

| Status             | Significado                                                                                             | Terminal |
| ------------------ | ------------------------------------------------------------------------------------------------------- | -------- |
| `queued`           | Aguardando início                                                                                       | Não      |
| `in_progress`      | O agent está trabalhando. `statusDetail: "delegated"` indica trabalho delegado a um processo mais longo | Não      |
| `waiting_approval` | Pausado aguardando aprovação humana no dashboard                                                        | Não      |
| `completed`        | Concluído — `output.text` traz a resposta do agent                                                      | Sim      |
| `failed`           | Algo deu errado — veja `error.code` e `error.message`                                                   | Sim      |
| `canceled`         | Cancelado antes de começar                                                                              | Sim      |

Respostas não terminais incluem um header `retry-after` com o intervalo sugerido entre consultas. Quando o run conclui:

```json theme={null}
{
  "id": "run_id",
  "status": "completed",
  "output": { "text": "Lead de alta prioridade: decisor em uma empresa de 200 pessoas..." },
  "completedAt": 1720000042000
}
```

<Note>
  Um run em `waiting_approval` retoma depois que alguém aprova a ação pendente
  no dashboard. Se você registrou um `callbackUrl`, também recebe um evento
  `run.waiting_approval` nesse momento — útil para avisar quem aprova.
</Note>

Prefere não consultar em loop? Registre um `callbackUrl` e receba um webhook assinado na conclusão — veja [Webhooks de conclusão](/pt-BR/api/webhooks).

## Listar runs

```bash theme={null}
curl "https://app.leme.ai/api/v1/agents/AGENT_ID/runs?limit=20" \
  -H "Authorization: Bearer leme_pat_v1_..."
```

Retorna `{ "runs": [...], "nextCursor": "..." }`, do mais recente para o mais antigo. Passe `cursor` para buscar a próxima página e `status` para filtrar (por exemplo, `status=failed`).

## Cancelar um run

```bash theme={null}
curl -X POST https://app.leme.ai/api/v1/runs/RUN_ID/cancel \
  -H "Authorization: Bearer leme_pat_v1_..."
```

Apenas runs ainda em `queued` podem ser cancelados. Um run já em execução retorna `409 not_cancellable`; cancelar um run já finalizado é inofensivo e devolve o recurso sem alteração.

## Continuar uma conversa

Cada run sem `sessionId` inicia uma sessão nova. Para manter contexto entre runs — uma conversa contínua com o mesmo agent — reutilize o `sessionId` retornado pelo primeiro run:

```bash theme={null}
curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_ID",
    "input": { "message": "Agora escreva um e-mail de follow-up para esse lead." }
  }'
```

A sessão aparece no dashboard como qualquer outra conversa, então seu time pode ler e assumir a qualquer momento.