DocumentationThreads and runs

Your assistants

Threads and runs

A thread holds a conversation with an assistant. Each question in it starts a run, which you track through to the response.

On this page
  1. One conversation turn
  2. Track the run
  3. Also available
  4. Configure a run
  5. Limits

One conversation turn

  1. Open a thread

    POST /v1/thread With the assistant’s ID.

  2. Ask the question

    POST /v1/thread/{id}/messages The user’s message.

  3. Start the run

    POST /v1/thread/{id}/runs The assistant works on this message. The response carries the run ID.

# 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"}'

Track the run

Poll the run until it ends. Once it has completed, the response is in output.

StatusWhat it means
queuedWaiting for a free worker
in_progressThe assistant is working
completedFinished, the response is ready
failedStopped by an error, described in error
canceledStopped before completion
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"))
Response
{
  "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
}

Also available

GET /v1/thread/{id}/messages The thread’s messages, up to 400 per page.

GET /v1/run/{id}/stream The response as server-sent events, while it is being written.

POST /v1/runs/{id}/stop Stops a run.

GET /v1/threads The user’s threads, filterable by assistant.

Configure a run

modelOverridetext
The model for this run only: flash or max.
reasoning_efforttext
Reasoning effort: none, low, medium or high.
maxStepsinteger
The maximum number of steps in the run, from 1 to 500.

Limits

  • 20 runs per minute per user
  • 600 requests per minute for the other routes
  • The number of runs per day depends on the workspace’s plan