CHANGELOG.md

Changelog

All notable changes to the Rust Apify API client are documented here. The format is based on Keep a Changelog and the project adheres to Semantic Versioning.

[0.7.0] - 2026-07-25

Added

• RunClient::get_with_options/RunGetOptions and BuildClient::get_with_options/BuildGetOptions for the waitForFinish server-side wait, also usable via actor.last_run()/task.last_run().
• DatasetCollectionClient::get_or_create_with_options/DatasetGetOrCreateOptions and the key-value-store equivalent, adding the JS-reference-only schema body field.
• RequestQueueClient::batch_add_requests_with_options/BatchAddRequestsOptions: byte-size chunk slicing, concurrent chunk calls, and retried unprocessedRequests, matching the JS reference. batch_add_requests now delegates to it.
• examples/tasks_schedules_webhooks.rs.
• tests/actor_run.rs::run_scoped_storage_update_and_delete, covering run-scoped storage PUT/DELETE (previously GET-only).

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-23T070817Z and crate version to 0.7.0.
• Removed the duplicated AI-generated/maintained notice; stated once in README.md.
• Behavior change: batch_add_requests folds a failed chunk's requests into unprocessedRequests instead of returning Err.
• Behavior/API change: TaskClient::start/call take new TaskStartOptions/TaskCallOptions instead of ActorStartOptions, matching the JS reference's narrower type and fixing a stray forcePermissionLevel param plus a dropped content_type.
• Behavior/API change: ActorClient::call takes new ActorCallOptions (drops wait_for_finish), fixing a footgun where it could block server-side before call's own polling began.
• Behavior/API change: ActorClient::validate_input/validate_input_for_build return bool instead of the raw response envelope.
• Behavior/API change: WebhookClient::test returns Option<WebhookDispatch> (None on 404).
• Behavior/API change: LogClient::stream/stream_with_options and RunClient::get_streamed_log* return Option<impl Stream<..>> (None on 404).
• Behavior/API change: UserClient::monthly_usage/monthly_usage_for_date/limits return Option<serde_json::Value>.
• ActorVersionCollectionClient::list no longer sends offset/limit/desc (the endpoint defines none).
• request_queue.rs::random_fraction now reuses the shared http_client::next_jitter generator instead of a second SystemTime-seeded source.

Fixed

• RequestQueueClient per-method timeouts now match the JS reference (5s/30s) instead of the 360s default.
• RequestQueueClient::get_request no longer sends clientKey, matching the JS reference.
• common::short_unique_name truncates the prefix (not the random suffix), fixing a name collision across concurrent suite runs.
• rust-integration-tests.yml's Test examples step now fails on zero executed tests, matching the main test step.
• rust-integration-tests.yml's path filter now includes README.md, docs/**, build.rs, and drops the inert (gitignored) Cargo.lock entry.
• tests/config.rs::make_client_honors_apify_api_url_env no longer mutates the real APIFY_TOKEN/APIFY_API_URL env vars, avoiding a race with concurrent tests.
• Batch-add's error-path unprocessedRequests entries omit method when absent instead of serializing "method": null.
• validate_input/validate_input_for_build default a missing valid field to false instead of erroring, matching the JS reference's falsy-on-undefined behavior.

Documentation

• Documented batch_add_requests_with_options/BatchAddRequestsOptions, ActorVersionClient/ActorEnvVarClient (+ collections), with_client_key, and "Creating a …" sections for tasks/schedules/webhooks/Actors.
• Fixed a self-contradictory docs/README.md error-handling example.
• Added BatchAddRequestsOptions/TaskStartOptions/TaskCallOptions/ActorVersion/ActorEnvVar to docs/README.md's Imports/model lists.
• Filled in previously-undocumented field types across ActorListOptions.sort_by, LastRunOptions, StoreListOptions, ListKeysOptions, GetRecordOptions, ListRequestsOptions, DatasetListItemsOptions, DatasetDownloadOptions, ActorBuildOptions, RunResurrectOptions, RunMetamorphOptions, RunChargeOptions, and docs/schedules.md's create fields.
• Corrected with_client_key's scope description and the request-lock example in docs/storages.md.
• Corrected three doc comments that overstated JS-parity (KeyValueStoreKeysIterator, get_streamed_log, the compress-once rationale in src/http_client.rs); the last was also consolidated into one explanation with a one-line pointer.
• src/lib.rs/src/http_client.rs/README.md no longer claim parity with a non-JS reference client.
• Tightened the ACTOR_RUN_ID justification comment in tests/actor_run.rs and dropped review-round provenance from tests/unit_http.rs doc comments.
• Documented RunClient/BuildClient::get_with_options and DatasetCollectionClient/KeyValueStoreCollectionClient::get_or_create_with_options (and their option types) in docs/runs.md/docs/builds.md/docs/storages.md/docs/README.md.
• Corrected the start/call argument-type notation in docs/actors.md/docs/tasks.md (generic <T: Serialize>, not argument-position impl Trait), matching the turbofish usage in every example.
• Qualified paginate_requests's doc to not oversell an exclusiveStartId capability the method doesn't expose.
• Corrected rust-integration-tests.yml's Test examples step comment to say it compile-checks the doc examples (only one is genuinely runnable), rather than implying broad runtime execution.

Internal

• Extracted shared helpers (last_run_client, is_terminal_status, encode_webhooks) to remove near-duplicate code; removed WebhookCollectionClient::with_base (identical to new).
• Removed the unused _root: ApifyClient parameter from RunClient::new.
• Named the SplitMix64 mixing constants in http_client.rs::next_jitter (now pub(crate), reused by request_queue.rs).
• Reused common::NOT_FOUND_STATUS_CODE in log.rs's stream 404 check instead of a raw literal; named the request_queue.rs empty-array byte constant; promoted the Content-Encoding header literals in http_client.rs to a HEADER_CONTENT_ENCODING const.

Tests

• Added a live assertion for the standalone ApifyClient::log(id) accessor.
• Added hermetic coverage for TaskStartOptions/ActorCallOptions query-param mapping.
• Added tests/actor.rs::actor_webhooks_and_default_build (ActorClient::webhooks()/default_build()) and tests/key_value_store.rs::keys_public_url_is_fetchable.
• Documented why the ACTOR_RUN_ID mutation in tests/actor_run.rs is race-free.
• Added hermetic coverage for validate_input's bare-body unwrap and the WebhookClient::test/LogClient::stream 404-to-None mappings.
• Replaced a tautological total >= 0 assertion with a load-bearing empty-collection check in actor_webhooks_and_default_build.
• Strengthened ~14 further tautological assert!(total >= 0) list-GET assertions into load-bearing consistency (items.len() <= limit, checked against the same response's limit rather than total since the latter raced under cargo test --all-targets's concurrent account load) or known-empty-collection checks.
• Made tests/webhook.rs::webhook_definition embed a unique fragment per call, matching the suite's UUID-isolation convention.

[0.6.1] - 2026-07-14

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-13T092445Z. The spec delta (added 402/408 error responses on the resurrect and run-sync-get-dataset-items endpoints, and relaxed the required constraints on the run/build/key-value-store/webhook stats sub-objects) needs no code change: error responses are handled generically and response models are forward-compatible.
• Bumped crate version to 0.6.1.

[0.6.0] - 2026-07-10

Added

• Lazy async pagination iterators on every collection client, via a shared generic ListIterator<T> (exported at the crate root). New iterate() methods on the actor, actor version, environment-variable, build, run, dataset, key-value-store, request-queue, schedule, task, webhook, and webhook-dispatch collection clients, plus DatasetClient::iterate_items() for dataset items. Each yields one item at a time, fetching pages on demand — the idiomatic counterpart to the reference client's async-iterable list results. The options' limit caps the total number of items yielded (matching the reference client), and ListIterator::with_chunk_size sets the per-request page size.
• KeyValueStoreClient::iterate_keys(), returning a cursor-based KeyValueStoreKeysIterator that auto-paginates a store's keys via exclusiveStartKey/nextExclusiveStartKey (the auto-paginating counterpart to list_keys, matching the reference client's listKeys() async-iterable).
• Re-exported StoreActorIterator at the crate root.

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-10T105921Z. The spec delta (added 401/402 error responses and relaxed field nullability/optionality) needs no code change: error responses are handled generically and response models are forward-compatible.
• StoreCollectionClient::iterate now uses the shared ListIterator, and StoreActorIterator is a type alias for ListIterator<ActorStoreListItem>. As part of this, store().iterate()'s options.limit changed from a per-page size (0.5.0) to a cap on the total number of items yielded, for consistency with the reference client and the other iterate() methods; set the per-page size with ListIterator::with_chunk_size instead. The StoreActorIterator type alias itself is unchanged.
• Corrected the src/models.rs module doc to describe forward-compatibility accurately.
• Documented ApifyClient::set_status_message and BuildClient::get_openapi_definition in the docs/ pages and README.
• Simplified the total-cap truncation in the offset and key-value-store iterators (removed a dead .max(0) clamp on an already-positive remaining count).
• Bumped crate version to 0.6.0.

Removed

• KeyValueStoreClient::get_records and GetRecordsOptions (GET /v2/key-value-stores/{storeId}/records).

Documentation

• Documented all ActorStartOptions fields in docs/actors.md (added the previously undocumented restart_on_error, force_permission_level, and webhooks), and linked the task start/call rows in docs/tasks.md to that field table.
• Listed JSONL in the download_items format summary in docs/storages.md for consistency with the DownloadItemsFormat variant list.
• Noted why the request-queue iterator is named paginate_requests (mirrors the reference JS paginateRequests) rather than an iterate_* verb.
• Made the run_store_actor example resilient to Store ranking shifts by falling back to the well-known apify/hello-world identifier, and cleaned up Option output in the get_account and iterate_store examples and the docs/README.md quick-start snippet.

[0.5.0] - 2026-07-10

Added

• RequestCompression enum and ApifyClientBuilder::request_compression to select the request-body encoding: brotli (Content-Encoding: br, default) or gzip (Content-Encoding: gzip).

Changed

• The User-Agent OS token now matches the reference client's os.platform() value (darwin, win32, sunos) instead of Rust-native spellings (macos, windows, solaris).
• Bumped crate version to 0.5.0.

[0.4.8] - 2026-07-09

Added

• Request bodies of at least 1024 bytes are now brotli-compressed and sent with Content-Encoding: br.

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-08T143931Z.
• Bumped crate version to 0.4.8.

[0.4.7] - 2026-07-07

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-07T132551Z.
• Bumped crate version to 0.4.7.

Documentation

• Corrected the last_run/LastRunOptions rustdoc comments: origin is now a documented query parameter on the last-run endpoints in the OpenAPI spec (the comments previously said it was undeclared).
• Fixed the README.md monthly_usage link to point at the Users section of docs/misc.md instead of the Logs section.

[0.4.6] - 2026-07-07

Changed

• Condensed earlier CHANGELOG.md entries into short change bullets.
• Bumped crate version to 0.4.6.

[0.4.5] - 2026-07-03

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-02T131926Z.
• Bumped crate version to 0.4.5.

Documentation

• Added chrono to the extra-dependency install instructions.
• Expanded the DatasetListItemsOptions/DatasetDownloadOptions and ActorBuildOptions field lists into per-field descriptions, and corrected the output_fields description.
• Removed a stray get_statistics bullet from the request-queue return-types list.

[0.4.4] - 2026-07-01

Changed

• Bumped API_SPEC_VERSION to v2-2026-07-01T115402Z.
• Bumped crate version to 0.4.4.

[0.4.3] - 2026-06-30

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-30T091455Z.
• Bumped crate version to 0.4.3.

Documentation

• examples/get_account.rs: import chrono::Utc explicitly so the snippet is self-contained.
• RunCollectionClient::list: added a rustdoc example for the two-argument list(ListOptions, RunListOptions) call.

[0.4.2] - 2026-06-29

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-29T142258Z (no in-scope API surface change).

[0.4.1] - 2026-06-29

Changed

• Documentation now states the client is "official, but experimental" and AI-generated/AI-maintained (crate-level rustdoc src/lib.rs, README.md, docs/README.md, and the Cargo.toml description).
• The crates.io publish workflow (.github/workflows/rust-publish.yml) now authenticates with Trusted Publishing (OIDC) via rust-lang/crates-io-auth-action@v1 instead of a stored CARGO_REGISTRY_TOKEN secret; the job gains id-token: write permission to mint the short-lived token.

[0.4.0] - 2026-06-26

Added

• ActorClient::last_run_with_options and TaskClient::last_run_with_options, plus LastRunOptions { status, origin } (re-exported at the crate root), adding an origin filter alongside status on the last-run endpoints. The existing last_run(status) delegates to it (additive).
• LogClient::get_with_options / stream_with_options and RunClient::get_streamed_log_with_options, plus LogOptions { raw } (re-exported), exposing the spec's optional raw query parameter on the log endpoints. The existing no-argument methods delegate with default options (additive).
• examples/raw_log.rs (covered by the Test examples CI step) exercising the raw-log path end-to-end.
• Tests: log_get_sends_raw_query_param; a raw-log assertion in the run_actor_and_read_outputs integration flow.

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-25T142310Z.
• Bumped crate version 0.3.0 → 0.4.0 (minor; additive APIs above).
• Tightened the build_user_agent isAtHome comment in src/common.rs (no behaviour change).

Documentation

• Documented the accepted last_run origin values (DEVELOPMENT, WEB, API, SCHEDULER) in docs/runs.md and referenced them from docs/actors.md / docs/tasks.md; corrected the TaskClient::last_run docstring example to "SCHEDULER"; showed an origin-filtered call in examples/run_and_last_run_storages.rs.

[0.3.0] - 2026-06-25

Fixed

• ListRequestsOptions.filter (for GET /v2/request-queues/{queueId}/requests) is now Option<Vec<String>> serialized comma-joined, matching the spec (an array of the enum values locked/pending). Breaking change to that field's type.
• The User-Agent isAtHome flag is now based solely on the APIFY_IS_AT_HOME environment variable.

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-24T105326Z.
• Bumped crate version 0.2.4 → 0.3.0 (minor; breaking filter type change).
• RunMetamorphOptions and RunChargeOptions are now re-exported at the crate root (additive).
• Documentation: the log_redirection example now redirects a separate Actor's run log; added model field tables for Task/Schedule/Webhook/WebhookDispatch; aligned monthly_usage docs on the non-panicking Value::get idiom; hardened the last_run example against eventual consistency; documented the crate-root import surface and the APIFY_TOKEN convention.

[0.2.4] - 2026-06-23

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-23T113219Z.
• Bumped crate version 0.2.3 → 0.2.4.

[0.2.3] - 2026-06-22

Changed

• CI: the manually triggered Publish Rust client to crates.io workflow (.github/workflows/rust-publish.yml) now also tags the released commit and creates a matching GitHub release. The tag (vX.Y.Z) is derived from the Cargo.toml version, validated as bare semver, and checked against existing local/remote tags; it is created before cargo publish, and the GitHub release step is idempotent. The dry_run input skips tag and release creation.

[0.2.2] - 2026-06-22

Added

• CI: a manually triggered (workflow_dispatch) Publish Rust client to crates.io workflow (.github/workflows/rust-publish.yml) that publishes the crate to crates.io. It runs the format/clippy/build gate, a cargo publish --dry-run check, then cargo publish. The registry token is read from the CARGO_REGISTRY_TOKEN repository secret. A dry_run input allows a packaging-only run.

Changed

• Packaging: added the homepage field (https://apify.com) to Cargo.toml.
• Documentation: added the "experimental, AI-generated and AI-maintained" disclaimer to the crate-level rustdoc (src/lib.rs), README.md and docs/README.md, and reworded the Cargo.toml description accordingly; documented ApifyClientError::as_api_error; removed dangling reference-style Markdown link brackets in docs/README.md and docs/misc.md; added a "Releasing" subsection to the README "Versioning" section.

[0.2.1] - 2026-06-19

Changed

• CI: added a standalone Test examples step that runs the examples/ programs end-to-end against the live API and the in-documentation snippets as doctests; Run integration tests now skips the example_* tests (via --skip example_).
• Documentation testing: the external docs/ pages are now compiled as doctests via #[doc = include_str!] in src/lib.rs, so every in-documentation rust snippet is verified.
• Documentation: added response-model field tables for ActorRun, Actor, Build, the shared storage-metadata fields of Dataset/KeyValueStore/RequestQueue, and User, each with a runnable no_run doctest.

[0.2.0] - 2026-06-19

Added

• ActorClient::validate_input_for_build — exposes the spec's optional build query parameter on POST /v2/actors/{actorId}/validate-input. The existing validate_input delegates with None.
• UserClient::monthly_usage_for_date — exposes the spec's optional date query parameter on GET /v2/users/me/usage/monthly. The existing monthly_usage delegates with None.
• Integration tests: get_monthly_usage_for_date; a validate_input_for_build call added to build_actor_flow.

Changed

• Bumped API_SPEC_VERSION to v2-2026-06-18T095846Z.

Fixed

• validate_input / validate_input_for_build no longer fail to parse the bare { "valid": ... } response (new internal post_action_raw helper skips data-envelope unwrapping).
• UserClient::monthly_usage's me-only guard error now names monthly_usage instead of the delegated monthly_usage_for_date.

[0.1.0] - 2026-06-18

Initial release of the official Rust client for the Apify API.

Added

• Resource-oriented async client (ApifyClient + ApifyClientBuilder) mirroring the JavaScript reference client.
• Resource clients for Actors, Actor builds, Actor runs, Actor tasks, datasets, key-value stores, request queues, schedules, webhooks, webhook dispatches, the Apify Store, users, Actor versions and environment variables, and logs.
• Convenience helpers: actor.call / task.call (start + wait + run), run.wait_for_finish and build.wait_for_finish, dataset push/list items, key-value store records, request queue operations, log retrieval and streaming (log redirection), and lazy iteration of Apify Store Actors (store().iterate()).
• Replaceable HTTP transport via the HttpBackend trait with a default reqwest backend.
• Automatic Bearer authentication, the mandated User-Agent header, and transparent retries with exponential backoff on 429/5xx/network errors.
• Public version constants CLIENT_VERSION and API_SPEC_VERSION (v2-2026-06-16T064758Z).
• Request-queue lock lifecycle: list_requests, list_and_lock_head, prolong_request_lock, delete_request_lock, unlock_requests, plus batch_add_requests / batch_delete_requests.
• Dataset download_items (JSON/CSV/XLSX/XML/RSS/HTML export) and get_statistics.
• KeyValueStoreClient::get_records — downloads all records from a store as a ZIP archive, with collection/prefix/signature filtering via GetRecordsOptions.
• Build get_openapi_definition.
• ApifyClient::set_status_message for setting the current run's status from inside an Actor.
• Public, shareable resource URLs with HMAC-SHA256 signing for private resources: DatasetClient::create_items_public_url, KeyValueStoreClient::get_record_public_url / create_keys_public_url, plus a configurable public_base_url.
• Format-specific dataset export options via DatasetDownloadOptions (attachment, bom, delimiter, skip_header_row, xml_root, xml_row).
• Full parameter coverage on list/start endpoints (my/sortBy for Actors; webhooks, restartOnError, forcePermissionLevel for run start; unwind/flatten/view/etc. for dataset items; includeUnrunnableActors for store; attachment for KVS records).
• Offline unit tests (mock HttpBackend) covering retry counting, 429/5xx retry vs. 4xx no-retry, network-error retry, backoff, error-envelope parsing and 404→None mapping.
• Integration test suite covering simple GETs and full CRUD flows for each resource.
• GitHub Actions workflow running formatting, clippy, build and integration tests.

Fixed

• Percent-encode URL path segments (key-value-store record keys, request-queue request IDs) so keys containing /, ?, #, spaces or non-ASCII no longer produce malformed URLs.
• get_record now sends attachment=true, matching the reference client's getRecord. get_record_with_options takes a GetRecordOptions { attachment, signature }; attachment defaults to true when unset.
• Request-queue request pagination (paginate_requests / RequestQueueRequestsIterator) now feeds the opaque nextCursor back as the cursor query parameter on subsequent pages, matching the reference client (previously pagination broke past the first page).
• User-Agent {language version} now reports the real compiler version captured at build time (via build.rs running rustc --version) instead of Rust/unknown.

Changed

• Added previously-missing spec query parameters: dataset items outputFields (list/download) and feedTitle/feedDescription (download); key-value-store keys collection/signature; key-value-store record signature (via GetRecordOptions); request-queue requests cursor/filter (via ListRequestsOptions); storage collection list unnamed/ownership (via StorageListOptions); run collection list startedAfter/startedBefore (via RunListOptions).
• get_record_with_options signature changed to take GetRecordOptions (was attachment: bool), exposing the spec signature param for reading records from private stores.
• ActorClient::default_build now takes a wait_for_finish: Option<i64> argument, matching the reference client's defaultBuild(options).
• Backoff doubling factor extracted to a named constant.
• RunClient::charge now takes RunChargeOptions { event_name, count, idempotency_key } and always sends an idempotency-key header (auto-generated when omitted), so a transport-retried charge is applied at most once.
• RunClient::metamorph now takes RunMetamorphOptions { build, content_type }.
• RunResurrectOptions gained max_items, max_total_charge_usd, and restart_on_error.
• RunListOptions::status is now Vec<String> (sent comma-separated).
• RunClient::abort now takes gracefully: Option<bool> instead of bool (None omits the query parameter).
• RequestQueueClient::batch_add_requests now splits inputs larger than the API's 25-per-call limit into chunks and merges the per-chunk processedRequests/unprocessedRequests results.