DocumentaçãoThreads e execuções

Os teus assistentes

Threads e execuções

Uma thread guarda uma conversa com um assistente. Cada pergunta inicia nela uma execução, que acompanhas até à resposta.

Nesta página
  1. Uma interação da conversa
  2. Acompanhar a execução
  3. Também disponível
  4. Ajustar uma execução
  5. Limites

Uma interação da conversa

  1. Abrir uma thread

    POST /v1/thread Com o identificador do assistente.

  2. Fazer a pergunta

    POST /v1/thread/{id}/messages A mensagem da pessoa.

  3. Iniciar a execução

    POST /v1/thread/{id}/runs O assistente trabalha nesta mensagem. A resposta inclui o identificador da execução.

# Open a thread with the assistant.
curl https://api.learnya.ai/v1/thread \
  -H "Authorization: Bearer $LEARNYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"assistantId": "ASSISTANT_ID", "title": "Ticket 42"}'

# Post the question.
curl https://api.learnya.ai/v1/thread/THREAD_ID/messages \
  -H "Authorization: Bearer $LEARNYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Where is my invoice?"}'

# Start the run on it. The answer carries the run id.
curl https://api.learnya.ai/v1/thread/THREAD_ID/runs \
  -H "Authorization: Bearer $LEARNYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"triggerMessageId": "MESSAGE_ID"}'

Acompanhar a execução

Consulta a execução até ao fim. Quando estiver concluída, a resposta está em output.

EstadoO que significa
queuedÀ espera de um worker livre
in_progressO assistente está a trabalhar
completedConcluída, a resposta está pronta
failedInterrompida por um erro, descrito em error
canceledParada antes do fim
import time

while True:
    reply = requests.get(f"{API}/run/{run_id}", headers=HEADERS)
    run = reply.json()
    if run["status"] in ("completed", "failed", "canceled"):
        break
    time.sleep(1)

if run["status"] == "completed":
    print(run["output"][0]["text"])
else:
    print(run["status"], run.get("error"))
Resposta
{
  "id": "c2a7e9d4-1b3f-4e6a-8c5d-9f0b2e4a6d18",
  "threadId": "8e4b1d6f-2c9a-4f7e-b3d5-0a6c8e2f4b91",
  "assistantId": "6f1c2b0e-3a4d-4c8e-9b7a-2d5e8f1a0c34",
  "status": "completed",
  "output": [
    { "type": "text", "text": "Your invoice 2026-114 was sent on 2 October." }
  ],
  "modelUsed": "learnya-flash",
  "error": null
}

Também disponível

GET /v1/thread/{id}/messages As mensagens da thread, até 400 por página.

GET /v1/run/{id}/stream A resposta em eventos do servidor, enquanto é escrita.

POST /v1/runs/{id}/stop Interrompe uma execução.

GET /v1/threads As threads da pessoa, filtráveis por assistente.

Ajustar uma execução

modelOverridetexto
O modelo apenas desta execução: flash ou max.
reasoning_efforttexto
O esforço de raciocínio: none, low, medium ou high.
maxStepsinteiro
O número máximo de passos da execução, de 1 a 500.

Limites

  • 20 execuções por minuto e por pessoa
  • 600 pedidos por minuto para as restantes rotas
  • O número de execuções por dia depende do plano do espaço de trabalho