Runs and logs

Listing the runs of an Aetherfy agent

A run on Aetherfy is one ephemeral execution of a type: job agent. List recent runs newest-first:

afy agents runs nightly-report
afy agents runs nightly-report --limit 50

The default limit is 20 and the maximum is 100.

The listing shows five columns:

Aetherfy lists only runs with a trigger source of cron or manual. Runs started by a parent agent are excluded from this listing — they belong to the parent’s history instead.

What the Aetherfy runs API returns

The equivalent Aetherfy REST call is:

GET /agents/{id}/runs

Each row Aetherfy returns carries these fields:

before is a keyset cursor rather than an offset, so paging backwards through a long history stays correct even as new runs arrive.

Run and deployment states on Aetherfy

Aetherfy uses one state vocabulary for both deployments and runs. Four of the states are terminal — once a record reaches them it will not change again.

completed applies to runs, which end by design. A long-lived service deployment that is working sits at active and stays there until a newer deployment supersedes it.

What decides completed versus failed for a run is the process exit code — see /agents/task-contract.

Agent status values on Aetherfy

An agent has its own status, separate from the state of any individual deployment or run.

usage_paused is the one to recognise on sight: the agent is not broken and nothing needs repairing in your code. Raise the limit or settle the payment at https://app.aetherfy.com/dashboard/settings/billing  and the agent resumes.

Retrieving logs from Aetherfy

Everything an agent writes to stdout and stderr becomes its logs on Aetherfy.

afy logs nightly-report

Scope the output to a single run, using a Run ID from afy agents runs:

afy logs nightly-report --run 01JABCDEF0123456789ABCDEF

Combined:

afy logs nightly-report --tail 200 --since 1h --level ERROR,WARN --stream stderr

One caveat worth knowing before you debug against it: on Aetherfy --follow polls, and it ignores both --tail and --since. It also does not honour JSON output. Use --follow to watch what happens next; use --tail and --since to look at what already happened.

Log record fields on Aetherfy

Every log record Aetherfy stores carries:

The system stream holds lines Aetherfy itself emits about the machine, as distinct from your program’s own output on stdout and stderr.

What Aetherfy does not record for you

Aetherfy logging is plain stdout/stderr capture, and nothing more. It does not auto-instrument calls your agent makes to model providers — there is no automatic capture of prompts, completions, token counts, latency or tool calls from an OpenAI, Anthropic or other SDK running inside your agent.

If you want that, log it yourself. A print() or logger.info() around the call lands in exactly the same place as the rest of your output and is searchable with afy logs --level:

import json, time
 
started = time.monotonic()
response = call_your_model(prompt)
print(json.dumps({
    "event": "llm_call",
    "model": "your-model-id",
    "elapsed_ms": round((time.monotonic() - started) * 1000),
    "prompt_chars": len(prompt),
}))

Keep the per-line and per-deployment limits below in mind if you log full prompts — they are easy to exceed.

Log limits and retention on Aetherfy

Aetherfy caps log volume in several dimensions. Logs are an operational aid, not a durable data store — write anything you need to keep to a real destination.

When an agent exceeds the per-line or volume caps, the Aetherfy log forwarder backs off and emits a marker in the stream so the gap is visible rather than silent:

[SYSTEM] N log line(s) dropped

If you see that marker, the agent is logging faster than Aetherfy will accept. Reduce per-line size or log volume — a very large payload dumped per iteration is the usual cause.