Clatter Labs
Console

Runs

Stream run events

View as Markdown

Server-sent events while a run works.

GETapi.agent.clatterlabs.xyz/v1/runs/{id}/eventsruns:read

Server-sent events while the run works: status when it changes, one step per agent message or tool call, then done with the final run. One connection lasts up to 10 minutes; reconnect with ?after=N to continue.

See Streaming events for a full client with reconnection.

Authorizations

Authorizationstringrequired

Your API key as a bearer token: Bearer clsk_.... Create keys in the Console.

X-Clatter-Accountstringrequired

The Account ID that owns the key, like CL-7K2M9QXA. Find it in Console › Settings. A missing value answers 401 missing_account_id; someone else's answers 401 account_mismatch.

Path parameters

idstringrequired

The run id.

Query parameters

afterintegerdefault: 0

Skip the first N steps (the number of step events you already have).

Response

text/event-stream

event: status{ status }

The run's status changed: queued, running, completed, failed or cancelled.

event: stepStep

One agent step.

event: doneRun

The finished run, same shape as Get a run.

event: timeout{ message, after }

The 10-minute connection limit was reached; the run continues. Reconnect with ?after= set to after.

event: error{ code, message }

The stream stopped (for example the key was revoked). Reconnect with ?after=N.

curl -N "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}

with requests.get("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events", headers=headers, stream=True) as r:
    for line in r.iter_lines(decode_unicode=True):
        if line:
            print(line)
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
};

const res = await fetch("https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events", { headers });
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(value); // "event: step\ndata: {...}\n\n"
}
event: status
data: {"status":"running"}

event: step
data: {"index":0,"type":"message","text":"I'll write hello.py and run it."}

event: step
data: {"index":1,"type":"tool","name":"computer_files","ok":true,"args":"{\"path\":\"hello.py\"}","output":"wrote 61 bytes"}

event: done
data: {"id":"4f0c2a6e-…","object":"run","status":"completed","output":"…"}
{
  "error": {
    "code": "not_found",
    "message": "No run with that id."
  }
}