Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,17 @@ All notable changes to the Apify Java client are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.14.1] - 2026-11-13

### Changed

- Updated to Apify OpenAPI specification `v2-2026-11-13T143025Z` (documentation only).
- Javadoc of `RunClient.charge` and `Actor.getActorStandby` uses the Server Actors wording.
- `RunClient.charge` docs say to call it from inside the Actor run, with the run's `APIFY_TOKEN`.
- `ActorRun.getUsageUsd` docs say when the field is present: runs you own that pay for platform usage, not standard pay-per-event Actors.
- `docs/runs.md` states that `abort`, `reboot`, and `metamorph` work on a `lastRun()` client.
- API token docs say that Apify Console shows a token only once.

## [0.14.0] - 2026-11-10

### Added
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Maven (Maven Central is a default repository, so no extra configuration is neede
<dependency>
<groupId>com.apify</groupId>
<artifactId>apify-client</artifactId>
<version>0.14.0</version>
<version>0.14.1</version>
</dependency>
```

Expand All @@ -35,7 +35,7 @@ repositories {
}

dependencies {
implementation 'com.apify:apify-client:0.14.0'
implementation 'com.apify:apify-client:0.14.1'
}
```

Expand All @@ -50,7 +50,7 @@ import com.apify.client.actor.ActorStartOptions;

class HelloApify {
public static void main(String[] args) {
// Your API token from https://console.apify.com/settings/integrations
// An API token created at https://console.apify.com/settings/integrations (shown only once)
ApifyClient client = ApifyClient.create(System.getenv("APIFY_TOKEN"));
ActorRun run = client.actor("apify/hello-world").call(null, new ActorStartOptions(), 120L).join();
System.out.println("Run " + run.getId() + " finished with status " + run.getStatus());
Expand Down Expand Up @@ -437,10 +437,10 @@ try {
The public `com.apify.client.Version` class (`import com.apify.client.Version;`) exposes two
constants:

- `Version.CLIENT_VERSION`: the semantic version of this client (`0.14.0`).
- `Version.CLIENT_VERSION`: the semantic version of this client (`0.14.1`).
- `Version.API_SPEC_VERSION`: the version of the [Apify OpenAPI specification](https://docs.apify.com/api/openapi.json)
(its `info.version` field) that this client's endpoints, parameters, and models were last generated
and checked against (`v2-2026-11-09T143926Z`). It is a snapshot, not a live compatibility
and checked against (`v2-2026-11-13T143025Z`). It is a snapshot, not a live compatibility
guarantee: the client keeps working against newer, backward-compatible spec revisions, but a
feature added to the API after this snapshot has no corresponding method here yet.

Expand Down
6 changes: 4 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,10 @@ compression, default headers, user-agent suffix, custom HTTP transport). `client
returns a client that sends every request with a different timeout (see
[Timeouts](../README.md#timeouts)).

Get your API token from the
[Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations).
Create an API token on the
[Apify Console → Settings → API & Integrations](https://console.apify.com/settings/integrations)
page. The Console shows the token only once, right after you create or rotate it, so copy it and
store it somewhere safe.

Every network-calling method returns a `CompletableFuture` (`java.util.concurrent.CompletableFuture`)
rather than blocking the calling thread; see [Asynchronous API](../README.md#asynchronous-api) in
Expand Down
24 changes: 15 additions & 9 deletions docs/runs.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,14 @@ To update the status message of a run other than the current one, call `update()
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.
> **Not every method works on a `lastRun()` client.** A `RunClient` obtained via
> `actor(id).lastRun(...)` / `task(id).lastRun(...)` targets the `runs/last` path. Reads (`get`,
> `dataset()`/`keyValueStore()`/`requestQueue()`, `log()`) are supported, and so are `abort`,
> `reboot`, and `metamorph`, which call the documented `runs/last/abort`, `runs/last/reboot`, and
> `runs/last/metamorph` endpoints with the same `status` and `origin` filters. The other mutating
> methods (`resurrect`, `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()`,
Expand All @@ -143,7 +145,8 @@ owning it, e.g. `"ANYONE_WITH_ID_CAN_READ"`, `"RESTRICTED"`, or `null` to follow
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
consumption, the latter as its USD cost and only for runs you own that pay for platform usage,
`null` for standard pay-per-event Actors; 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()`,
Expand Down Expand Up @@ -177,10 +180,13 @@ nullable), `getMemoryMbytes()` (`Long`, nullable), `getDiskMbytes()` (`Long`, nu
`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).
charged (required for multi-tenant Server Actor runs, omitted otherwise). See
[Charge for a request](https://docs.apify.com/platform/actors/monetize/server-actors#charge-for-a-request).
Call `charge` from inside the Actor run, with the API token the run received at startup in the
`APIFY_TOKEN` environment variable.

```java
client.run("RUN_ID").charge(new RunChargeOptions("my-event").count(3L)).join();
client.run(System.getenv("ACTOR_RUN_ID")).charge(new RunChargeOptions("my-event").count(3L)).join();
```

`MetamorphOptions` uses plain values `build(String)` and `contentType(String)`.
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<groupId>com.apify</groupId>
<artifactId>apify-client</artifactId>
<version>0.14.0</version>
<version>0.14.1</version>
<packaging>jar</packaging>

<name>Apify Java Client</name>
Expand Down
6 changes: 5 additions & 1 deletion src/main/java/com/apify/client/ApifyClientBuilder.java
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,11 @@ public final class ApifyClientBuilder {

ApifyClientBuilder() {}

/** Sets the API token used for authentication (sent as a Bearer token). */
/**
* Sets the API token used for authentication (sent as a Bearer token). Create a token on the <a
* href="https://console.apify.com/settings/integrations">Integrations page</a> in Apify Console,
* which shows it only once, right after you create or rotate it.
*/
public ApifyClientBuilder token(String token) {
this.token = token;
return this;
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/com/apify/client/Version.java
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ public final class Version {
* The semantic version of this client library (see <a href="https://semver.org/">SemVer</a>).
* Changes to the public interface other than additive ones are considered breaking changes.
*/
public static final String CLIENT_VERSION = "0.14.0";
public static final String CLIENT_VERSION = "0.14.1";

/**
* The version of the Apify OpenAPI specification this client was generated and verified against.
* Corresponds to the {@code info.version} field of the Apify OpenAPI document.
*/
public static final String API_SPEC_VERSION = "v2-2026-11-09T143926Z";
public static final String API_SPEC_VERSION = "v2-2026-11-13T143025Z";

private Version() {}
}
7 changes: 6 additions & 1 deletion src/main/java/com/apify/client/actor/Actor.java
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,12 @@ public List<String> getCategories() {
return categories == null ? List.of() : Collections.unmodifiableList(categories);
}

/** Standby-mode configuration for this Actor, if standby mode has ever been configured. */
/**
* Standby-mode configuration for this Actor, if standby mode has ever been configured. For
* details, see <a
* href="https://docs.apify.com/platform/actors/development/programming-interface/server-actors">Develop
* Server Actors</a>.
*/
public ActorStandby getActorStandby() {
return actorStandby;
}
Expand Down
7 changes: 6 additions & 1 deletion src/main/java/com/apify/client/run/ActorRun.java
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,12 @@ public ActorRunUsage getUsage() {
return usage;
}

/** As {@link #getUsage()}, converted to USD; only present where {@link #getUsage()} is. */
/**
* Platform usage costs in USD, broken down by billable unit. Only present if you own the run and
* pay for platform usage (pay per usage, or pay per event with usage costs, such as runs of
* single-tenant Server Actors). Not available for standard pay-per-event Actors, and requires an
* authentication token.
*/
public ActorRunUsage getUsageUsd() {
return usageUsd;
}
Expand Down
12 changes: 9 additions & 3 deletions src/main/java/com/apify/client/run/RunClient.java
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,14 @@ public CompletableFuture<ActorRun> resurrect(RunResurrectOptions options) {

/**
* Charges for a pay-per-event Actor run: records occurrences of a named event. Only meaningful
* for runs of pay-per-event Actors.
* for runs of pay-per-event Actors. Call it from the Actor run itself, with the API token the run
* received at startup in the {@code APIFY_TOKEN} environment variable.
*
* <p>To charge a request to a multi-tenant Server Actor, set {@link
* RunChargeOptions#requestId(String)} to the {@code X-Actor-Request-ID} header value of the
* request. See <a
* href="https://docs.apify.com/platform/actors/monetize/server-actors#charge-for-a-request">Charge
* for a request</a>.
*
* <p>An idempotency key is always sent (generated if not provided), so a retried charge is
* applied at most once.
Expand All @@ -182,8 +189,7 @@ public CompletableFuture<Void> charge(RunChargeOptions options) {
body.put("requestId", requestId);
}
Map<String, String> headers = Map.of(CHARGE_IDEMPOTENCY_HEADER, idempotencyKey);
// Route through mergedParams like the run's other actions, so a last-run-seeded context charges
// the same run its read methods resolve to (its pinned status/origin filters are preserved).
// Kept consistent with the other actions; there is no runs/last/charge endpoint.
String url = ctx.mergedParams(new QueryParams()).applyToUrl(ctx.subUrl("charge"));
return ctx.http
.call(
Expand Down
34 changes: 34 additions & 0 deletions src/test/java/com/apify/client/ClientBehaviourRegressionTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,40 @@ void lastRunForwardsStatusFilterToNestedStorages() {
assertTrue(log.lastUrl.contains("origin=API"), log.lastUrl);
}

@Test
void lastRunAbortRebootAndMetamorphCallTheLastRunEndpointsWithTheFilters() {
// The spec documents runs/last/{abort,reboot,metamorph} for Actors and tasks, so these calls
// on a filtered last-run client must keep the pinned status and origin filters.
LastRunOptions filters = new LastRunOptions().status("RUNNING").origin("API");
String runBody = "{\"data\":{\"id\":\"run123\"}}";

MockTransport abort = MockTransport.ofConstant(200, runBody);
client(abort).actor("me/x").lastRun(filters).abort(null).join();
assertLastRunUrl(abort.lastUrl, "actors/me~x/runs/last/abort");

MockTransport reboot = MockTransport.ofConstant(200, runBody);
client(reboot).actor("me/x").lastRun(filters).reboot().join();
assertLastRunUrl(reboot.lastUrl, "actors/me~x/runs/last/reboot");

MockTransport metamorph = MockTransport.ofConstant(200, runBody);
client(metamorph)
.actor("me/x")
.lastRun(filters)
.metamorph("apify/other-actor", Map.of("foo", "bar"), new MetamorphOptions())
.join();
assertLastRunUrl(metamorph.lastUrl, "actors/me~x/runs/last/metamorph");

MockTransport taskAbort = MockTransport.ofConstant(200, runBody);
client(taskAbort).task("me/t").lastRun(filters).abort(null).join();
assertLastRunUrl(taskAbort.lastUrl, "actor-tasks/me~t/runs/last/abort");
}

private static void assertLastRunUrl(String url, String expectedPath) {
assertTrue(url.contains(expectedPath), url);
assertTrue(url.contains("status=RUNNING"), url);
assertTrue(url.contains("origin=API"), url);
}

@Test
void plainRunNestedStoragesCarryNoInheritedFilter() {
// A non-last-run client has no pinned params, so nested accessors stay filter-free.
Expand Down
Loading