Agent Logs

Overview

Every Wiro agent appends one structured ActivityEvent JSON line per tool call, LLM turn boundary, scheduled task run and billed turn, plus each message that arrives on a connected Telegram, Slack or Discord channel. Secrets (matched by field name and by high-entropy value), internal tool-call IDs and API credentials are redacted before an event is written, so what shows up in Logs is safe to show end users.

A daily JSONL file is written for each calendar day; files older than 7 days are gzipped, files older than 180 days are deleted by the agent's daily maintenance cron.

The feed also lists what people and API keys did to the agent: starts and stops, renames, skill, connector and billing changes, connections and deleted log days, each with who did it. These who-did-what rows don't depend on the agent running.

The endpoints below are owner-or-team-admin scoped. Plain members of the agent's team receive useragent-team-admin-required (code 97); outside callers receive useragent-access-denied.

ActivityEvent Shape

Every event is a JSON object with this base shape:

{
  "ts": "2026-05-03T14:00:10.234Z",
  "kind": "tool_completed",
  "tool": "web_fetch",
  "title": "Fetched https://blog.example.com/weekly-roundup-12",
  "summary": {
    "url": "https://blog.example.com/weekly-roundup-12",
    "status": 200,
    "bytes": 18432
  },
  "durationMs": 1840,
  "ok": true,
  "userUuid": "ada-uuid",
  "user": {
    "uuid": "ada-uuid",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "email": "ada@example.com",
    "username": "ada",
    "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
    "avatarinitials": "AL"
  }
}

Token-usage events

A token_usage event records the token spend and credit deduction for one billed turn: a chat reply, a cron run, or a voice post-call. A token_usage_idempotent event carries the same shape for a replayed usage callback that was already billed (informational; it does not deduct again). On top of the base ActivityEvent fields, these events add:

{
  "ts": "2026-05-03T14:02:55.310Z",
  "kind": "token_usage",
  "title": "Token Usage",
  "model": "openai/gpt-5.4",
  "tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
  "tokencost": 5,
  "durationMs": 4200,
  "calls": 2,
  "remainingcredits": 9995,
  "userUuid": "system",
  "user": null
}

Who-did-what rows

Logs and LogsFile also return what people and API keys did to the agent, and LogsList lists the days that have such rows. These rows sit in the same events list, in time order, with an AGENT_* value in kind. They come on top of the kinds above, which keep their meaning.

{
  "ts": "2026-05-03T09:12:44.000Z",
  "kind": "AGENT_RENAMED",
  "title": "Agent renamed from \"Inbox Bot\" to \"Inbox Watcher\"",
  "ok": true,
  "summary": { "title": "Inbox Watcher", "previoustitle": "Inbox Bot", "fields": ["title"] },
  "userUuid": "ada-uuid",
  "user": {
    "uuid": "ada-uuid",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "email": "ada@example.com",
    "username": "ada",
    "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
    "avatarinitials": "AL"
  }
}

title is the line to show. summary holds the names and amounts behind it, never a connector value. userUuid and user name who did it. When an API key made the change, the title ends with (API key "<project name>") or (via API key).

Note rows

Two more kinds say what part of a day is missing. They are notes, so they carry a title and no ok.

POST /UserAgent/Logs

Live tail of the agent's activity feed. Returns the last N events for the requested date (defaults to today).

Polling: leave 30 seconds or more between repeated polls.

Request

curl -X POST "https://api.wiro.ai/v1/UserAgent/Logs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "lines": 200 }'

Response

{
  "result": true,
  "errors": [],
  "date": "2026-05-03",
  "totalLines": 1428,
  "events": [
    {
      "ts": "2026-05-03T14:02:55.310Z",
      "kind": "token_usage",
      "title": "Token Usage",
      "model": "openai/gpt-5.4",
      "tokens": { "input": 3450, "output": 820, "cacheRead": 2400, "cacheWrite": 0, "total": 6670 },
      "tokencost": 5,
      "durationMs": 4200,
      "calls": 2,
      "remainingcredits": 9995,
      "userUuid": "system",
      "user": null
    },
    {
      "ts": "2026-05-03T14:02:54.902Z",
      "kind": "tool_completed",
      "tool": "exec",
      "title": "POST api.wiro.ai/v1/Run/google/nano-banana",
      "summary": {
        "method": "POST",
        "host": "api.wiro.ai",
        "path": "/v1/Run/google/nano-banana",
        "headers": ["Content-Type: application/json", "x-api-key: ***"],
        "body": { "prompt": "A paper boat on a calm lake at sunrise" }
      },
      "durationMs": 640,
      "ok": true,
      "userUuid": "system",
      "user": null
    },
    {
      "ts": "2026-05-03T14:00:10.305Z",
      "kind": "tool_completed",
      "tool": "exec",
      "title": "Posted: \"Weekly Roundup\"",
      "summary": {
        "title": "Weekly Roundup",
        "url": "https://blog.example.com/weekly-roundup-12",
        "categories": ["AI", "Tutorial"]
      },
      "durationMs": 1840,
      "ok": true,
      "userUuid": "system",
      "user": null
    },
    {
      "ts": "2026-05-03T13:30:00.000Z",
      "kind": "cron_finished",
      "title": "Cron ran: Scheduled Skill (cs-cron-blog-scanner)",
      "summary": { "jobId": "0f3c2a1b-7d4e-4c8f-9a6b-2e5d1c7f8a90", "status": "ok" },
      "durationMs": 4210,
      "ok": true,
      "userUuid": "system",
      "user": null
    },
    {
      "ts": "2026-05-03T13:14:42.118Z",
      "kind": "turn_ended",
      "title": "Agent turn completed",
      "summary": {
        "preview": "Here is this week's roundup draft…",
        "messageCount": 6
      },
      "durationMs": 8104,
      "ok": true,
      "userUuid": "ada-uuid",
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "ada@example.com",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      }
    }
  ]
}

With a lines cap, older who-did-what rows of the day can take the place of the oldest agent events, up to half of the answer, so a stop from this morning stays in reach on a busy day. The answer stays within lines.

Reading a stopped agent. When the agent isn't running, or its host doesn't answer, Logs still answers result: true for a day with who-did-what rows. events starts with a runtime_log_unavailable note, followed by those rows, and totalLines counts the note:

{
  "result": true,
  "errors": [],
  "date": "2026-05-03",
  "totalLines": 3,
  "events": [
    {
      "ts": "2026-05-03T16:20:11.000Z",
      "kind": "runtime_log_unavailable",
      "title": "The agent's own turns and tool calls can be read while it runs",
      "userUuid": "system",
      "user": null
    },
    {
      "ts": "2026-05-03T16:20:11.000Z",
      "kind": "AGENT_STOPPED",
      "title": "Agent stopped",
      "ok": true,
      "userUuid": "ada-uuid",
      "user": { "uuid": "ada-uuid", "firstname": "Ada", "lastname": "Lovelace" }
    },
    {
      "ts": "2026-05-03T09:12:44.000Z",
      "kind": "AGENT_CREDENTIAL_SAVED",
      "title": "Connector setting saved: wiro.apikey",
      "ok": true,
      "summary": { "fields": ["wiro.apikey"] },
      "userUuid": "ada-uuid",
      "user": { "uuid": "ada-uuid", "firstname": "Ada", "lastname": "Lovelace" }
    }
  ]
}

A day without such rows answers with one of the errors below.

POST /UserAgent/LogsList

Returns the dates that have activity for this agent: days with a log file and days that only have who-did-what rows. Useful for rendering a date-picker.

Response

{
  "result": true,
  "errors": [],
  "dates": [
    { "date": "2026-05-03", "sizeBytes": 184220, "compressed": false },
    { "date": "2026-05-02", "sizeBytes": 41280,  "compressed": true  },
    { "date": "2026-05-01", "sizeBytes": 0,      "compressed": false }
  ]
}

Each entry exposes date (YYYY-MM-DD, sorted newest-first), sizeBytes (raw byte size on disk; compressed size when compressed: true), and compressed (true once the day's log has been compressed to <date>.jsonl.gz; false for the active day's plain .jsonl). sizeBytes is 0 on a day with who-did-what rows and no log file, for example a day whose log was deleted. Reading either form via LogsFile returns the same decoded events. The host retains activity files for 180 days (rolling); older dates are removed and won't appear here.

Reading a stopped agent. When the agent isn't running, or its host doesn't answer, and it has who-did-what days, LogsList still answers result: true with those days and two more fields:

{
  "result": true,
  "errors": [],
  "runtimeUnavailable": "not_running",
  "note": "The agent's own log days can be read while it runs, so this list may be missing days.",
  "dates": [
    { "date": "2026-05-03", "sizeBytes": null, "compressed": false },
    { "date": "2026-05-01", "sizeBytes": null, "compressed": false }
  ]
}

An agent with no who-did-what days answers with one of the errors below.

POST /UserAgent/LogsFile

Reads the full log of a specific date and returns every event in it, who-did-what rows included. A stopped agent and a deleted day read as on Logs. Use this for "Download today's activity" buttons or for off-band analysis.

Response

{
  "result": true,
  "errors": [],
  "date": "2026-05-02",
  "truncated": false,
  "events": [
    {
      "ts": "2026-05-02T08:00:20.142Z",
      "kind": "turn_started",
      "title": "Agent turn started",
      "summary": { "preview": "Hi, can you draft a roundup post?" },
      "userUuid": "ada-uuid",
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "ada@example.com",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      }
    },
    {
      "ts": "2026-05-02T08:00:19.870Z",
      "kind": "user_message",
      "title": "User: Hi, can you draft a roundup post?",
      "summary": { "preview": "Hi, can you draft a roundup post?" },
      "user": {
        "uuid": "ada-uuid",
        "firstname": "Ada",
        "lastname": "Lovelace",
        "email": "ada@example.com",
        "username": "ada",
        "avatar": "https://cdn.wiro.ai/avatars/ada.webp",
        "avatarinitials": "AL"
      }
    }
  ]
}

Events are returned newest first (descending by ts), same as the live tail, so events[0] is the most recent; do not re-reverse. The user field follows the same resolution rules as the live tail above (see the Logs section's "About the user field" callout).

POST /UserAgent/LogsDelete

Deletes the agent's own turns and tool calls for one date: its activity file and the gzipped sibling, if present. Who-did-what rows stay, so the date can stay in LogsList with sizeBytes: 0. The deletion adds an AGENT_LOG_DAY_DELETED row on the day you make it, and reads of an earlier day you deleted start with a runtime_log_deleted note that says when. Idempotent: deleting an already-gone date is a success no-op.

Response

{
  "result": true,
  "errors": [],
  "date": "2026-05-01",
  "removed": { "plain": false, "gz": true }
}

removed.{plain,gz} reports which physical files were actually deleted. Both false is also a success (file was already gone).

Usage Patterns

Live polling for an in-app activity feed

Polling Logs every 30 seconds is the recommended cadence:

async function pollActivity(useragentguid, onEvents) {
  let lastTs = 0;

  setInterval(async () => {
    const { data } = await axios.post(
      'https://api.wiro.ai/v1/UserAgent/Logs',
      { useragentguid, lines: 200 },
      { headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' } }
    );

    const fresh = data.events.filter(e => Date.parse(e.ts) > lastTs);
    if (fresh.length === 0) return;

    onEvents(fresh);
    lastTs = Date.parse(fresh[0].ts);
  }, 30_000);
}

Daily download for off-band analysis

# 1) discover available dates
curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsList" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321" }'

# 2) download a specific date's full file
curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsFile" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02" }' \
  > logs-2026-05-02.json

Filtering server-side by kind

The endpoints don't support server-side filtering, so apply filters client-side:

import requests

resp = requests.post(
    "https://api.wiro.ai/v1/UserAgent/LogsFile",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02"}
).json()

cron_runs = [e for e in resp["events"] if e["kind"] == "cron_finished"]
print(f"{len(cron_runs)} cron runs on 2026-05-02")
for e in cron_runs:
    summary = e.get("summary") or {}
    print(f"  {e['title']} status={summary.get('status')}")

Delete a day

LogsDelete removes the agent's own turns and tool calls for one day without waiting for the 180-day rotation. Who did what to the agent that day stays in the log:

curl -X POST "https://api.wiro.ai/v1/UserAgent/LogsDelete" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "useragentguid": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", "date": "2026-05-02" }'

Errors

Logs, LogsFile and LogsList answer with the last three errors only when there are no who-did-what rows to show. LogsDelete needs the agent on a host every time.

Retention & Rotation

Who-did-what rows are kept for the same 180 days.

What's Next

• Agent Transactions: Credit ledger for the same useragent
• Agent Messaging: User-facing message exchanges (with full prompts and responses)
• Agent Overview: Full agent endpoint catalog