runs.md

Runs

Access the run collection with client.runs() (or client.actor(id).runs() / client.task(id).runs()) and a single run with client.run(id).

RunCollectionClient

Method	Description
list(ListOptions, RunListOptions)	List runs. Completes with PaginationList<ActorRun>.
iterate(ListOptions, RunListOptions, Long chunkSize)	Lazy Flow.Publisher<ActorRun> over all matching runs; the options' limit caps the total yielded (null/unset or non-positive = all), chunkSize sets the per-request page size (null = server default).

RunListOptions adds status(List<String>) (e.g. SUCCEEDED, RUNNING; sent comma-separated), deployment(List<String>) (filter Actor Standby runs by serving pool: SINGLE_TENANT, MULTI_TENANT_FREE_USERS, MULTI_TENANT_PAYING_USERS, MULTI_TENANT_OWNER_PAID; needs a status filter with only non-terminal statuses, declared by client.runs() and client.actor(id).runs()), declared by every scope's endpoint (client.runs(), client.actor(id).runs(), client.task(id).runs()), and startedAfter(String) / startedBefore(String) (ISO-8601), declared only by the account-wide client.runs() and the Actor-scoped client.actor(id).runs() endpoints; the task-scoped client.task(id).runs() endpoint's spec does not declare these two parameters at all, so set them only when listing at one of the other two scopes. All parameters a given scope declares compose (e.g. a status filter combined with a start-time window on client.runs()).

PaginationList<ActorRun> runs = client.runs().list(
    new ListOptions().limit(10L),
    new RunListOptions().status(List.of("SUCCEEDED"))).join();

RunClient

Method	Description
get()	Fetch the run. Completes with Optional<ActorRun>.
getWithWait(Long waitForFinishSecs)	Fetch, optionally waiting server-side for the run to finish (the API caps server-side waiting at 60s; the request timeout is extended by that hold). Completes with Optional<ActorRun>.
update(Object)	Update the run. Completes with ActorRun.
delete()	Delete the run.
abort(Boolean gracefully)	Abort the run (null = server default). Completes with ActorRun.
metamorph(String targetActorId, Object input, MetamorphOptions)	Metamorph into another Actor. Completes with ActorRun.
reboot()	Reboot the run. Completes with ActorRun.
resurrect(RunResurrectOptions)	Resurrect a finished run (status SUCCEEDED, FAILED, ABORTED or TIMED-OUT). Completes with ActorRun.
charge(RunChargeOptions)	Charge a pay-per-event run for a named event. Completes with no value (CompletableFuture<Void>).
waitForFinish(Long waitSecs)	Poll until the run finishes (null waits indefinitely). Completes with ActorRun.
dataset() / keyValueStore() / requestQueue()	Clients for the run's default storages.
iterateDatasetItems(DatasetListItemsOptions) / iterateDatasetItems(DatasetListItemsOptions, Long chunkSize, Long pollIntervalSecs, Class<T>)	A lazy Flow.Publisher over the items of the run's default dataset while the run is still producing them; it ends once the run has finished and every item has been read. While the run is active, each poll yields the rows below the dataset's itemCount and then waits up to pollIntervalSecs (default 5) for the run to finish; afterwards the rows past the lagging itemCount are read a page at a time. The options' offset/limit bound the dataset rows scanned (desc is ignored), chunkSize is the rows per request (default 1000). On a lastRun() client it sticks to the run its first request resolves to.
log()	A LogClient for the run's log (see Store, users & logs).
getStreamedLog()	Completes with a StreamedLog that redirects the live log to a default per-run logger.
getStreamedLog(StreamedLogOptions)	As above, with a custom destination / options.

If waitSecs elapses before the run reaches a terminal state, waitForFinish returns the run's current (non-terminal) status rather than throwing or blocking further; check isTerminal() on the result and call waitForFinish again (or poll) if you need to keep waiting. ActorClient/ TaskClient's call(...) overloads (see Actors/Tasks) return this same possibly-non-terminal ActorRun for the same reason: call is start followed by waitForFinish, so a call with a short waitSecs on a long-running Actor can return before the run finishes.

If the id instead keeps returning 404 (e.g. a typo, or it was never created) waitForFinish does not poll it for the whole wait budget: a 404 is tolerated for up to 3 seconds (database-replica lag right after a run/build is created), past which it throws that NotFoundError.

Streamed log redirection

getStreamedLog() completes with a StreamedLog: a helper that follows the run's live raw log in a background thread and redirects each complete, timestamped message to a destination. It is AutoCloseable; call start() (itself asynchronous; it completes once the live stream is open and the background reader thread is running) to begin redirection and stop() (or close(), via try-with-resources) to end it.

With no options, messages go to an SLF4J Logger at INFO level, prefixed with the Actor name and run id (looked up automatically). StreamedLogOptions customizes it:

• toLog(Consumer<String>): send each complete message to your own consumer instead of the default logger.
• prefix(String): override the auto-built prefix used by the default logger.
• fromStart(boolean): when false, skip log lines produced before redirection started (default true).

A run that has not logged anything yet (e.g. still queued for resources, see waitForResources) serves its log as a stream that ends at once; StreamedLog reopens it, with capped exponential backoff, until it actually delivers content, rather than silently giving up. If stop()/close() is called before that happens, it fetches the log in one plain request instead, so whatever was logged by then is still delivered.

The toLog consumer runs on the background reader thread, one message at a time. stop() and close() wait for the consumer to finish its current message and up to 1 second for a message still arriving, deliver the last message, and then return. If the calling thread is interrupted, they close the stream, keep the interrupt flag, and return before the reader has ended, so the last message may arrive after they return, and start() throws until a later stop() or close() has joined the reader.

Calling close() from inside the consumer is supported: it signals the stop and returns without waiting, and the reader ends once the consumer returns. start() throws until a later stop() or close() from another thread has joined the reader.

RunClient runClient = client.run("RUN_ID");
List<String> collected = new ArrayList<>();
try (StreamedLog streamedLog =
    runClient.getStreamedLog(new StreamedLogOptions().toLog(collected::add).fromStart(true)).join()) {
  streamedLog.start().join();
  runClient.waitForFinish(120L).join();
}

For raw stream access without redirection, use log().stream(new LogOptions().raw(true)); use log() for the full log text or for non-raw/download options.

To set the current run's status message from inside an Actor, use the top-level client.setStatusMessage(...) (see the docs index). To update the status message of a run other than the current one, call update() on its RunClient directly:

client.run("RUN_ID").update(Map.of("statusMessage", "half way there", "isStatusMessageTerminal", false)).join();

lastRun() clients are for reads. A RunClient obtained via actor(id).lastRun(...) / task(id).lastRun(...) targets the runs/last path and is intended for reading (get, dataset()/keyValueStore()/requestQueue(), log()). The mutating methods (abort, reboot, resurrect, metamorph, charge, update, delete) require a concrete run and have no runs/last endpoint; resolve the id first (lastRun(...).get().join() then client.run(id)). The type exposes them uniformly, but calling them on a last-run client fails server-side.

ActorRun fields include getId(), getActId(), getUserId(), getStatus(), getStatusMessage(), getStartedAt(), getFinishedAt(), getBuildId(), getDefaultDatasetId(), getDefaultKeyValueStoreId(), getDefaultRequestQueueId(), getContainerUrl(), plus isTerminal(). The status is one of READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED; isTerminal() is true for the finished states (SUCCEEDED, FAILED, TIMED-OUT, ABORTED).

ActorRun also exposes the Server Actor deployment that served the run, getStandby() (ActorRunStandby; getDeployment() is SINGLE_TENANT or one of the MULTI_TENANT_* pools, null for a run not started by a Server Actor request; charges in a multi-tenant pool need RunChargeOptions.requestId(...)), and getConsoleUrl(), getOutput() (Map<String, String>), getEventUsage() (Map<String, JsonNode>), getAccountedChargedEventCounts(), getExternalChargedTotalUsd(), getIntegrationTracking() and getCreatedByOrganizationMemberUserId(); getMeta() adds getActorRunId(), getWebhookDispatchId(), getScheduledAct2Id() and getScheduledActorTaskId().

ActorRun additionally exposes: getGeneralAccess() (String; who can access the run without owning it, e.g. "ANYONE_WITH_ID_CAN_READ", "RESTRICTED", or null to follow the account/Actor default), getChargedEventCounts() (Map<String, Long>; per-event-type charge counts for pay-per-event Actors, null otherwise), getPricingInfo() (JsonNode; shape depends on the Actor's pricing model), getUsage() / getUsageUsd() (ActorRunUsage; per-billable-unit resource consumption, the latter as its USD cost; see below), getUsageTotalUsd() (Double; the run's total cost in USD, combining platform usage and/or event costs depending on pricing model), getStats() (ActorRunStats; runtime metrics; getInputBodyLen(), getMigrationCount(), getRebootCount(), getRestartCount(), getResurrectCount(), getMemAvgBytes()/getMemMaxBytes()/getMemCurrentBytes(), getCpuAvgUsage()/getCpuMaxUsage()/getCpuCurrentUsage(), getNetRxBytes()/getNetTxBytes(), getDurationMillis(), getRunTimeSecs(), getMetamorph(), getComputeUnits(); any other field is still reachable via the inherited getExtra()), getOptions() (ActorRunOptions; the run configuration actually applied, which may differ from what was requested; see below), getMeta() (ActorRunMeta; getOrigin(), getClientIp(), getUserAgent(), getScheduleId(), getScheduledAt(); how and, if triggered by a schedule, when the run was initiated), getBuildNumber() (String; the build's semver-like number, e.g. "0.0.36"), getExitCode() (Integer; the process exit code once finished), isContainerServerReady() (Boolean; whether the container's HTTP server can accept requests), getGitBranchName() (String; the git branch the build was built from, if any), and getStorageIds() (JsonNode; a {datasets, keyValueStores, requestQueues} map of aliased storage IDs for the run, each with at least a "default" entry). Any field not covered by a typed getter is still available via the inherited getExtra() (see the docs index).

ActorRunUsage (getUsage()/getUsageUsd()) exposes one nullable Double getter per billable unit: getActorComputeUnits(), getDatasetReads(), getDatasetWrites(), getKeyValueStoreReads(), getKeyValueStoreWrites(), getKeyValueStoreLists(), getRequestQueueReads(), getRequestQueueWrites(), getDataTransferInternalGbytes(), getDataTransferExternalGbytes(), getProxyResidentialTransferGbytes(), getProxySerps(). Each is null when the run's Actor did not incur that kind of usage.

ActorRunOptions (getOptions()) exposes: getBuild() (String), getTimeoutSecs() (Long, nullable), getMemoryMbytes() (Long, nullable), getDiskMbytes() (Long, nullable), getMaxItems() (Long, nullable), getMaxTotalChargeUsd() (Double, nullable), getRestartOnError() (Boolean, nullable).

RunChargeOptions (constructed with the required event name) uses plain values: count(Long), idempotencyKey(String), auto-generated when unset so a transport-retried charge is applied at most once, and requestId(String), the X-Actor-Request-ID of the Server Actor request being charged (required for multi-tenant Server Actor runs, omitted otherwise).

client.run("RUN_ID").charge(new RunChargeOptions("my-event").count(3L)).join();

MetamorphOptions uses plain values build(String) and contentType(String). RunResurrectOptions fields: build(String), memoryMbytes(Long), timeoutSecs(Long), maxItems(Long), maxTotalChargeUsd(Double), restartOnError(Boolean).