From 570402320c7bc688f69def31e222680e3dd552de Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 09:11:54 +0000 Subject: [PATCH 01/10] docs: clarify run-sync OUTPUT record is a convention, not canonical output The synchronous Actor/task run endpoints implied every Actor has a single canonical output stored under the OUTPUT key. Clarify that OUTPUT is only the default key-value store record key (the outputRecordKey default), that Actors aren't required to write it, that results are often in a dataset, and that it's unrelated to the Actor output schema. Also rename the POST run-sync summary to reflect it returns a key-value store record. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../parameters/runAndBuildParameters.yaml | 5 ++-- .../actor-tasks@{actorTaskId}@run-sync.yaml | 18 ++++++++++++++- .../paths/actors/acts@{actorId}@run-sync.yaml | 23 +++++++++++++++---- 3 files changed, 39 insertions(+), 7 deletions(-) diff --git a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml index 6aadf96ffb..c820e3e0ce 100644 --- a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml +++ b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml @@ -313,8 +313,9 @@ outputRecordKey: name: outputRecordKey in: query description: | - Key of the record from run's default key-value store to be returned - in the response. By default, it is `OUTPUT`. + Key of the record from the run's default key-value store to return in the + response. Defaults to `OUTPUT`. Actors aren't required to store a record + under this key, so if it doesn't exist the response contains no data. style: form explode: true schema: diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index d7040c3a58..84d0636e7d 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -3,7 +3,15 @@ get: - Actor tasks summary: Run task synchronously description: | - Run a specific task and return its output. + Runs a specific task and returns its output. + + The response contains the record stored under the `OUTPUT` key in the run's + default key-value store. This is a convention, not a guarantee - Actors aren't + required to store a record under this key, so the response may not contain any + data. Use the `outputRecordKey` query parameter to return a different record. + Many Actors store their results in a dataset instead. The `OUTPUT` record is + unrelated to an Actor's [output + schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -65,6 +73,14 @@ post: description: | Runs an Actor task and synchronously returns its output. + The response contains the record stored under the `OUTPUT` key in the run's + default key-value store. This is a convention, not a guarantee - Actors aren't + required to store a record under this key, so the response may not contain any + data. Use the `outputRecordKey` query parameter to return a different record. + Many Actors store their results in a dataset instead. The `OUTPUT` record is + unrelated to an Actor's [output + schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). + The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself). diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml index c98921d222..2f410eabdf 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml @@ -1,14 +1,23 @@ post: tags: - Actors/Actor runs - summary: Run Actor synchronously and return output + summary: Run Actor synchronously and return key-value store record description: | Runs a specific Actor and returns its output. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually application/json). - The HTTP response contains Actors `OUTPUT` record from its default - key-value store. + + The response contains the record stored under the `OUTPUT` key in the run's + default key-value store. This is a convention, not a guarantee - Actors aren't + required to store a record under this key, so the response may not contain any + data. Use the `outputRecordKey` query parameter to return a different record. + Many Actors store their results in a dataset instead; to get those, use the + Run Actor synchronously and get dataset items endpoint. + + The `OUTPUT` record is unrelated to an Actor's [output + schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema), + which defines how an Actor describes its results. The Actor is started with the default options; you can override them using various URL query parameters. @@ -87,7 +96,13 @@ get: - Actors/Actor runs summary: Run Actor synchronously without input description: | - Runs a specific Actor and returns its output. + Runs a specific Actor and returns its output. The response contains the + record stored under the `OUTPUT` key in the run's default key-value store. + This is a convention, not a guarantee - the record may not exist, in which + case the response contains no data. Use the `outputRecordKey` query parameter + to return a different record. The `OUTPUT` record is unrelated to an Actor's + [output + schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). The run must finish in 300 seconds otherwise the API endpoint returns a timeout error. The Actor is not passed any input. From 80073eb38cb76ca1b6cf1164794c9d8a808acd00 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 09:14:37 +0000 Subject: [PATCH 02/10] docs: link run-sync OUTPUT record to Actor output object concept Reword the clarification so the OUTPUT key-value store record is explicitly distinguished from the Actor output object, linking to the output object definition in the output schema docs. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../actor-tasks@{actorTaskId}@run-sync.yaml | 14 ++++++++------ .../paths/actors/acts@{actorId}@run-sync.yaml | 13 +++++++------ 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index 84d0636e7d..6464cb3cf5 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -9,9 +9,10 @@ get: default key-value store. This is a convention, not a guarantee - Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a different record. - Many Actors store their results in a dataset instead. The `OUTPUT` record is - unrelated to an Actor's [output - schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). + Many Actors store their results in a dataset instead. This `OUTPUT` record is + not to be confused with the Actor + [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), + which is a separate concept defined by the Actor's output schema. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -77,9 +78,10 @@ post: default key-value store. This is a convention, not a guarantee - Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a different record. - Many Actors store their results in a dataset instead. The `OUTPUT` record is - unrelated to an Actor's [output - schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). + Many Actors store their results in a dataset instead. This `OUTPUT` record is + not to be confused with the Actor + [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), + which is a separate concept defined by the Actor's output schema. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml index 2f410eabdf..1222129c8c 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml @@ -15,9 +15,9 @@ post: Many Actors store their results in a dataset instead; to get those, use the Run Actor synchronously and get dataset items endpoint. - The `OUTPUT` record is unrelated to an Actor's [output - schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema), - which defines how an Actor describes its results. + This `OUTPUT` record is not to be confused with the Actor + [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), + which is a separate concept defined by the Actor's output schema. The Actor is started with the default options; you can override them using various URL query parameters. @@ -100,9 +100,10 @@ get: record stored under the `OUTPUT` key in the run's default key-value store. This is a convention, not a guarantee - the record may not exist, in which case the response contains no data. Use the `outputRecordKey` query parameter - to return a different record. The `OUTPUT` record is unrelated to an Actor's - [output - schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema). + to return a different record. This `OUTPUT` record is not to be confused with + the Actor + [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), + which is a separate concept defined by the Actor's output schema. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error. The Actor is not passed any input. From af76bd41a513b16c1f3e01a5cf008cb399b5c21d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 09:21:54 +0000 Subject: [PATCH 03/10] docs: clarify Actor output object vs result storage in input-and-output Rewrite the Output section to match the actor-whitepaper model: the Actor output object is defined solely by the output schema, returned via API immediately when the run starts, and links to results that may live in the dataset, key-value store, or elsewhere - rather than equating output with the dataset. Also complete the page description to cover output. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../platform/actors/running/input_and_output.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/sources/platform/actors/running/input_and_output.md b/sources/platform/actors/running/input_and_output.md index 27e8c7c8ce..bef3155df2 100644 --- a/sources/platform/actors/running/input_and_output.md +++ b/sources/platform/actors/running/input_and_output.md @@ -1,6 +1,6 @@ --- title: Input and output -description: Configure your Actor's input parameters using Apify Console, locally or via API. Access parameters in key-value stores from your Actor's code. +description: Learn how Actors receive input and where they store their output, including the Actor output object and how to access run results from Console or the API. sidebar_position: 2 slug: /actors/running/input-and-output --- @@ -43,16 +43,18 @@ If the Actor is configured by developer to use [dynamic memory](../development/a ## Output -While the input object provides a way to instruct Actors, an Actor can also generate an output, usually stored in its default [Dataset](../../storage/dataset), but some additional files might be stored in its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn more about its output. +An Actor can produce results in several places. Structured, tabular results are usually stored in the run's default [Dataset](../../storage/dataset), while files and other unstructured data go to its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn what an Actor produces and where it stores it. For more details about storages, visit the [Storage](../../storage/index.md) section. -For more details about storages, visit the [Storage](../../storage/index.md) section. +To describe where its results are and how to reach them, an Actor can define an [output schema](/platform/actors/development/actor-definition/output-schema). The platform uses this schema to automatically generate the Actor _output object_ - an immutable JSON object whose properties link to the run's results. The output object is defined solely by the output schema, not by the Actor's code, and the API returns it as the run's `output` property immediately when the run starts, without waiting for the run to finish or for the results to be produced. This makes it useful for previewing results, generating API examples, and building integrations. -You can quickly access the Actor's output from the run detail page: +The output object is separate from the storages that hold the data: its properties point to results wherever they live, whether that's the dataset, the key-value store, or a URL exposed by the running Actor. + +You can quickly access the Actor's results from the run detail page: ![Actor output](./images/input_and_output/actor-output.png) -And to access all the data associated with the run, see the **Storage** tab, where you can explore the Actor's default [Dataset](../../storage/dataset), [Key-value store](../../storage/key-value-store), and [Request queue](../../storage/request-queue): +To access all the data associated with the run, open the **Storage** tab, where you can explore the run's default [Dataset](../../storage/dataset), [Key-value store](../../storage/key-value-store), and [Request queue](../../storage/request-queue): ![Actor output](./images/input_and_output/actor-storage.png) -You can also use [API](https://docs.apify.com/api/v2) to retrieve the output. To learn more about this, read the [Run an Actor or task and retrieve data via API](/academy/api/run-actor-and-retrieve-data-via-api) tutorial. +You can also use the [API](https://docs.apify.com/api/v2) to retrieve the results. To learn more, read the [Run an Actor or task and retrieve data via API](/academy/api/run-actor-and-retrieve-data-via-api) tutorial. From 4f3c6fac86c1a88eb9bcfcacaedd2d043f49715a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 09:30:12 +0000 Subject: [PATCH 04/10] docs: distinguish Actor output from single storage across docs Reword dataset-schema, key-value-store-schema, running, Make, n8n, and academy pages so they stop equating an Actor's output with one storage. Where the text means the dataset items or the produced results, say that explicitly, consistent with the output-object model defined by the output schema. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../academy/platform/deploying_your_code/inputs_outputs.md | 2 +- sources/academy/tutorials/api/using_apify_from_php.md | 2 +- .../development/actor_definition/dataset_schema/index.md | 6 +++--- .../actor_definition/key_value_store_schema/index.md | 2 +- sources/platform/actors/running/index.md | 2 +- .../integrations/workflows-and-notifications/make/index.md | 6 +++--- .../integrations/workflows-and-notifications/n8n/index.md | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/sources/academy/platform/deploying_your_code/inputs_outputs.md b/sources/academy/platform/deploying_your_code/inputs_outputs.md index db05c0338f..c0959e6764 100644 --- a/sources/academy/platform/deploying_your_code/inputs_outputs.md +++ b/sources/academy/platform/deploying_your_code/inputs_outputs.md @@ -127,7 +127,7 @@ print(solution) ## Writing output {#writing-output} -Similarly to reading input, you can write the Actor's output either by using the Apify SDK in Node.js or by manually writing a utility function to do so. +Similarly to reading input, you can write the Actor's results either by using the Apify SDK in Node.js or by manually writing a utility function to do so. ### Writing output with the Apify SDK diff --git a/sources/academy/tutorials/api/using_apify_from_php.md b/sources/academy/tutorials/api/using_apify_from_php.md index 43bae729df..ac584844ce 100644 --- a/sources/academy/tutorials/api/using_apify_from_php.md +++ b/sources/academy/tutorials/api/using_apify_from_php.md @@ -83,7 +83,7 @@ You should see information about the run, including its ID and the ID of its def ## Getting the results from dataset -Actors usually store their output in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset. +Actors usually store their results in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset. ```php // Replace with the run ID you from earlier diff --git a/sources/platform/actors/development/actor_definition/dataset_schema/index.md b/sources/platform/actors/development/actor_definition/dataset_schema/index.md index 3cee05779d..d2adb2edc6 100644 --- a/sources/platform/actors/development/actor_definition/dataset_schema/index.md +++ b/sources/platform/actors/development/actor_definition/dataset_schema/index.md @@ -1,7 +1,7 @@ --- title: Dataset schema specification sidebar_position: 5 -description: Define a dataset schema to control how your Actor output data is structured, validated, and displayed in Apify Console UI and API responses. +description: Define a dataset schema to control how your Actor's dataset is structured, validated, and displayed in Apify Console, the API, and integrations. slug: /actors/development/actor-definition/dataset-schema sidebar_label: Dataset schema --- @@ -280,11 +280,11 @@ Create multiple views for different use cases. This e-commerce scraper offers Ma ## Fields -The `fields` property defines the structure of each dataset item using [JSON Schema](https://json-schema.org/). It enables validation and provides metadata that help humans and AI agents understand your Actor's output. +The `fields` property defines the structure of each dataset item using [JSON Schema](https://json-schema.org/). It enables validation and provides metadata that help humans and AI agents understand the data in your dataset. ### Why define fields -When AI agents interact with Actors through the MCP server or API, they rely on field metadata to understand the Actor's output. Including `title`, `description`, and `example` properties lets agents: +When AI agents interact with Actors through the MCP server or API, they rely on field metadata to understand the data in your dataset. Including `title`, `description`, and `example` properties lets agents: - Understand the meaning of each output field - Chain Actors together by matching inputs to outputs diff --git a/sources/platform/actors/development/actor_definition/key_value_store_schema/index.md b/sources/platform/actors/development/actor_definition/key_value_store_schema/index.md index de94055476..59d0527e52 100644 --- a/sources/platform/actors/development/actor_definition/key_value_store_schema/index.md +++ b/sources/platform/actors/development/actor_definition/key_value_store_schema/index.md @@ -2,7 +2,7 @@ title: Key-value store schema specification sidebar_label: Key-value store schema sidebar_position: 6 -description: Define a key-value store schema to organize records into named collections with content type validation, making Actor output easier to navigate and browse. +description: Define a key-value store schema to organize records into collections with content type validation, making your Actor's key-value store easier to navigate. slug: /actors/development/actor-definition/key-value-store-schema --- diff --git a/sources/platform/actors/running/index.md b/sources/platform/actors/running/index.md index caf44c0c84..9e719156a8 100644 --- a/sources/platform/actors/running/index.md +++ b/sources/platform/actors/running/index.md @@ -116,4 +116,4 @@ print(dataset_items) The newly started Actor runs under the account associated with the provided `token`, so all consumed resources are charged to this user account. -Internally, the `call()` function invokes the [Run Actor](/api/v2/act-runs-post) API endpoint, waits for the Actor to finish, and reads its output using the [Get dataset items](/api/v2/dataset-items-get) API endpoint. +Internally, the `call()` function invokes the [Run Actor](/api/v2/act-runs-post) API endpoint, waits for the Actor to finish, and reads its results from the default dataset using the [Get dataset items](/api/v2/dataset-items-get) API endpoint. diff --git a/sources/platform/integrations/workflows-and-notifications/make/index.md b/sources/platform/integrations/workflows-and-notifications/make/index.md index d53b4bba61..ff6fa4b33c 100644 --- a/sources/platform/integrations/workflows-and-notifications/make/index.md +++ b/sources/platform/integrations/workflows-and-notifications/make/index.md @@ -85,7 +85,7 @@ You can find this dataset ID in the variables generated by the previous "Run an #### Step 3: Add the Google Sheets "Create Spreadsheet Rows" module -Finally, add the Google Sheets "Bulk Add Rows" module to your scenario. This module will automatically create new rows in a Google Sheets file to store the Actor's output. +Finally, add the Google Sheets "Bulk Add Rows" module to your scenario. This module will automatically create new rows in a Google Sheets file to store the Actor's results. In the "Spreadsheet ID" field, provide the ID of the target Google Sheets file, which you can find in its URL. Configure the column range (e.g., "A-Z") and map the data retrieved from the "Get Dataset Items" module to the row values. @@ -109,7 +109,7 @@ For this example, we will use the "Google Maps Review Scraper" Actor. #### Step 2: Add the Apify "Get Dataset Items" module -Add the "Get Dataset Items" module to your scenario to retrieve the output of the Actor run. +Add the "Get Dataset Items" module to your scenario to retrieve the items from the Actor run's default dataset. In the "Dataset ID" field, provide the default dataset ID from the Actor run. You can find the dataset ID in the variables generated by the "Watch Actor Runs" module. @@ -117,7 +117,7 @@ In the "Dataset ID" field, provide the default dataset ID from the Actor run. Yo #### Step 3: Add the Google Sheets "Create Spreadsheet Rows" module -Finally, add the Google Sheets "Bulk Add Rows" module to your scenario, which will create new rows in the specified Google Sheets file to store the Actor's output. +Finally, add the Google Sheets "Bulk Add Rows" module to your scenario, which will create new rows in the specified Google Sheets file to store the Actor's results. In the "Spreadsheet ID" field, enter the ID of the target Google Sheets file, which you can find in its URL. Configure the column range (e.g., "A-Z") and map the data retrieved from the "Get Dataset Items" module to the row values. diff --git a/sources/platform/integrations/workflows-and-notifications/n8n/index.md b/sources/platform/integrations/workflows-and-notifications/n8n/index.md index b16a9c0279..ecf7835aaa 100644 --- a/sources/platform/integrations/workflows-and-notifications/n8n/index.md +++ b/sources/platform/integrations/workflows-and-notifications/n8n/index.md @@ -123,7 +123,7 @@ Actions allow you to perform operations like running an Actor within a workflow. - **Wait for finish**: Whether to wait for the run to finish before continuing. If true, the node will wait for the run to complete (successfully or not) before moving to the next node ![Apify Node](../../images/n8n-run-actor-example.png) 1. Add another Apify operation called **Get Dataset Items**. - - Set **Dataset ID** parameter as **defaultDatasetId** value received from the previous **Run Actor** node. This will give you the output of the Actor run + - Set **Dataset ID** parameter as **defaultDatasetId** value received from the previous **Run Actor** node. This will give you the items from the Actor run's default dataset ![Apify Node](../../images/n8n-get-dataset-items-example.png) 1. Add any subsequent nodes (e.g. Google Sheets) to process or store the output 1. Save and execute the workflow From 056597005560b85820e3f88cbd07d0c9faf51105 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 12:21:20 +0000 Subject: [PATCH 05/10] docs: reword run-sync descriptions to "returns a key-value store record" Apply reviewer feedback: the synchronous run endpoints return a key-value store record, not a generic Actor output. Updated the first sentence of all four plain run-sync endpoint descriptions for consistency. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml | 4 ++-- apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index 6464cb3cf5..e869519646 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -3,7 +3,7 @@ get: - Actor tasks summary: Run task synchronously description: | - Runs a specific task and returns its output. + Runs a specific task and returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a convention, not a guarantee - Actors aren't @@ -72,7 +72,7 @@ post: - Actor tasks summary: Run task synchronously description: | - Runs an Actor task and synchronously returns its output. + Runs an Actor task and synchronously returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a convention, not a guarantee - Actors aren't diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml index 1222129c8c..ba79d64c65 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml @@ -3,7 +3,7 @@ post: - Actors/Actor runs summary: Run Actor synchronously and return key-value store record description: | - Runs a specific Actor and returns its output. + Runs a specific Actor and returns a key-value store record. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually application/json). @@ -96,7 +96,7 @@ get: - Actors/Actor runs summary: Run Actor synchronously without input description: | - Runs a specific Actor and returns its output. The response contains the + Runs a specific Actor and returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a convention, not a guarantee - the record may not exist, in which case the response contains no data. Use the `outputRecordKey` query parameter From d926dd739da7a9bc896f0f19bcd2e70364cf5e72 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 12:22:55 +0000 Subject: [PATCH 06/10] docs: align run-sync task GET description with POST wording Reviewer follow-up: make both GET and POST first sentences in the actor-task run-sync endpoint read identically as "Runs an Actor task and synchronously returns a key-value store record." Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index e869519646..8970694a99 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -3,7 +3,7 @@ get: - Actor tasks summary: Run task synchronously description: | - Runs a specific task and returns a key-value store record. + Runs an Actor task and synchronously returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a convention, not a guarantee - Actors aren't From afdd9298ea6ed142759be3fd4adbfce032005ab6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 12:26:40 +0000 Subject: [PATCH 07/10] docs: describe OUTPUT record as legacy approach replaced by output object The OUTPUT key-value store record isn't a convention - it's a legacy way of returning results that the Actor output object replaces. Reword the four run-sync descriptions accordingly and fold in the output object link. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../actor-tasks@{actorTaskId}@run-sync.yaml | 24 ++++++++---------- .../paths/actors/acts@{actorId}@run-sync.yaml | 25 ++++++++----------- 2 files changed, 20 insertions(+), 29 deletions(-) diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index 8970694a99..4f72b84ab8 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -6,13 +6,11 @@ get: Runs an Actor task and synchronously returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's - default key-value store. This is a convention, not a guarantee - Actors aren't - required to store a record under this key, so the response may not contain any - data. Use the `outputRecordKey` query parameter to return a different record. - Many Actors store their results in a dataset instead. This `OUTPUT` record is - not to be confused with the Actor - [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), - which is a separate concept defined by the Actor's output schema. + default key-value store. This is a legacy approach that has been replaced by + the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); + Actors aren't required to store a record under this key, so the response may + not contain any data. Use the `outputRecordKey` query parameter to return a + different record. Many Actors store their results in a dataset instead. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -75,13 +73,11 @@ post: Runs an Actor task and synchronously returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's - default key-value store. This is a convention, not a guarantee - Actors aren't - required to store a record under this key, so the response may not contain any - data. Use the `outputRecordKey` query parameter to return a different record. - Many Actors store their results in a dataset instead. This `OUTPUT` record is - not to be confused with the Actor - [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), - which is a separate concept defined by the Actor's output schema. + default key-value store. This is a legacy approach that has been replaced by + the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); + Actors aren't required to store a record under this key, so the response may + not contain any data. Use the `outputRecordKey` query parameter to return a + different record. Many Actors store their results in a dataset instead. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml index ba79d64c65..f5237ba0ea 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml @@ -9,15 +9,12 @@ post: the Actor (usually application/json). The response contains the record stored under the `OUTPUT` key in the run's - default key-value store. This is a convention, not a guarantee - Actors aren't - required to store a record under this key, so the response may not contain any - data. Use the `outputRecordKey` query parameter to return a different record. - Many Actors store their results in a dataset instead; to get those, use the - Run Actor synchronously and get dataset items endpoint. - - This `OUTPUT` record is not to be confused with the Actor - [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), - which is a separate concept defined by the Actor's output schema. + default key-value store. This is a legacy approach that has been replaced by + the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); + Actors aren't required to store a record under this key, so the response may + not contain any data. Use the `outputRecordKey` query parameter to return a + different record. Many Actors store their results in a dataset instead; to get + those, use the Run Actor synchronously and get dataset items endpoint. The Actor is started with the default options; you can override them using various URL query parameters. @@ -98,12 +95,10 @@ get: description: | Runs a specific Actor and returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. - This is a convention, not a guarantee - the record may not exist, in which - case the response contains no data. Use the `outputRecordKey` query parameter - to return a different record. This `OUTPUT` record is not to be confused with - the Actor - [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition), - which is a separate concept defined by the Actor's output schema. + This is a legacy approach that has been replaced by the Actor + [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); + the record may not exist, in which case the response contains no data. Use the + `outputRecordKey` query parameter to return a different record. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error. The Actor is not passed any input. From 617c4bc013681a5f1b4b3dd30a748b2049661498 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 12:42:27 +0000 Subject: [PATCH 08/10] docs: refer to Actor results in dataset-schema description Reviewer feedback: describe the dataset schema as controlling how the Actor's results are structured, validated, and displayed. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../actors/development/actor_definition/dataset_schema/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/actor_definition/dataset_schema/index.md b/sources/platform/actors/development/actor_definition/dataset_schema/index.md index d2adb2edc6..5f0b1532e3 100644 --- a/sources/platform/actors/development/actor_definition/dataset_schema/index.md +++ b/sources/platform/actors/development/actor_definition/dataset_schema/index.md @@ -1,7 +1,7 @@ --- title: Dataset schema specification sidebar_position: 5 -description: Define a dataset schema to control how your Actor's dataset is structured, validated, and displayed in Apify Console, the API, and integrations. +description: Define a dataset schema to control how your Actor's results are structured, validated, and displayed in Apify Console, the API, and integrations. slug: /actors/development/actor-definition/dataset-schema sidebar_label: Dataset schema --- From e6accf51cbeb207806411f678623034f328f46d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 12:44:42 +0000 Subject: [PATCH 09/10] docs: note results may be in default or additional dataset Reviewer feedback on the input-and-output Output section. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- sources/platform/actors/running/input_and_output.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/running/input_and_output.md b/sources/platform/actors/running/input_and_output.md index bef3155df2..6b7654c3e9 100644 --- a/sources/platform/actors/running/input_and_output.md +++ b/sources/platform/actors/running/input_and_output.md @@ -43,7 +43,7 @@ If the Actor is configured by developer to use [dynamic memory](../development/a ## Output -An Actor can produce results in several places. Structured, tabular results are usually stored in the run's default [Dataset](../../storage/dataset), while files and other unstructured data go to its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn what an Actor produces and where it stores it. For more details about storages, visit the [Storage](../../storage/index.md) section. +An Actor can produce results in several places. Structured, tabular results are usually stored in the run's default (or additional) [Dataset](../../storage/dataset), while files and other unstructured data go to its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn what an Actor produces and where it stores it. For more details about storages, visit the [Storage](../../storage/index.md) section. To describe where its results are and how to reach them, an Actor can define an [output schema](/platform/actors/development/actor-definition/output-schema). The platform uses this schema to automatically generate the Actor _output object_ - an immutable JSON object whose properties link to the run's results. The output object is defined solely by the output schema, not by the Actor's code, and the API returns it as the run's `output` property immediately when the run starts, without waiting for the run to finish or for the results to be produced. This makes it useful for previewing results, generating API examples, and building integrations. From f2de4e34ffde102d662df8cb7653697bb151085d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 24 Jun 2026 13:05:31 +0000 Subject: [PATCH 10/10] docs: address review feedback on output wording and parameters - Remove the "Many Actors store their results in a dataset instead" sentence from the run-sync descriptions (results can be in multiple datasets, KVS records, or none). - Move the run-sync-only outputRecordKey parameter into its own runSyncParameters.yaml component file. - Emphasize that an Actor's results generally go into its storages in the deploying-your-code tutorial. - Apply the suggested wording in the PHP tutorial. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc --- .../parameters/runAndBuildParameters.yaml | 12 ------------ .../components/parameters/runSyncParameters.yaml | 15 +++++++++++++++ .../actor-tasks@{actorTaskId}@run-sync.yaml | 8 ++++---- .../paths/actors/acts@{actorId}@run-sync.yaml | 7 +++---- .../deploying_your_code/inputs_outputs.md | 2 +- .../academy/tutorials/api/using_apify_from_php.md | 2 +- 6 files changed, 24 insertions(+), 22 deletions(-) create mode 100644 apify-api/openapi/components/parameters/runSyncParameters.yaml diff --git a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml index c820e3e0ce..71d0a45322 100644 --- a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml +++ b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml @@ -309,15 +309,3 @@ scheduleId: type: string example: asdLZtadYvn4mBZmm -outputRecordKey: - name: outputRecordKey - in: query - description: | - Key of the record from the run's default key-value store to return in the - response. Defaults to `OUTPUT`. Actors aren't required to store a record - under this key, so if it doesn't exist the response contains no data. - style: form - explode: true - schema: - type: string - example: OUTPUT diff --git a/apify-api/openapi/components/parameters/runSyncParameters.yaml b/apify-api/openapi/components/parameters/runSyncParameters.yaml new file mode 100644 index 0000000000..bc6898e1e4 --- /dev/null +++ b/apify-api/openapi/components/parameters/runSyncParameters.yaml @@ -0,0 +1,15 @@ +# Parameters specific to the run-sync endpoint family (Run Actor or task +# synchronously). These do not apply to the asynchronous run endpoints. + +outputRecordKey: + name: outputRecordKey + in: query + description: | + Key of the record from the run's default key-value store to return in the + response. Defaults to `OUTPUT`. Actors aren't required to store a record + under this key, so if it doesn't exist the response contains no data. + style: form + explode: true + schema: + type: string + example: OUTPUT diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml index 4f72b84ab8..e96d48c353 100644 --- a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml +++ b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml @@ -10,7 +10,7 @@ get: the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a - different record. Many Actors store their results in a dataset instead. + different record. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -34,7 +34,7 @@ get: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/maxItems" # XXX: do we support maxTotalChargeUsd for task runs? - $ref: "../../components/parameters/runAndBuildParameters.yaml#/build" - - $ref: "../../components/parameters/runAndBuildParameters.yaml#/outputRecordKey" + - $ref: "../../components/parameters/runSyncParameters.yaml#/outputRecordKey" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/webhooks" responses: "201": @@ -77,7 +77,7 @@ post: the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a - different record. Many Actors store their results in a dataset instead. + different record. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -114,7 +114,7 @@ post: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/maxTotalChargeUsd" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/restartOnError" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/build" - - $ref: "../../components/parameters/runAndBuildParameters.yaml#/outputRecordKey" + - $ref: "../../components/parameters/runSyncParameters.yaml#/outputRecordKey" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/webhooks" requestBody: description: "" diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml index f5237ba0ea..5c98e0fc8b 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml @@ -13,8 +13,7 @@ post: the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a - different record. Many Actors store their results in a dataset instead; to get - those, use the Run Actor synchronously and get dataset items endpoint. + different record. The Actor is started with the default options; you can override them using various URL query parameters. @@ -32,7 +31,7 @@ post: operationId: act_runSync_post parameters: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId" - - $ref: "../../components/parameters/runAndBuildParameters.yaml#/outputRecordKey" + - $ref: "../../components/parameters/runSyncParameters.yaml#/outputRecordKey" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/timeout" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/memory" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/maxItems" @@ -115,7 +114,7 @@ get: operationId: act_runSync_get parameters: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId" - - $ref: "../../components/parameters/runAndBuildParameters.yaml#/outputRecordKey" + - $ref: "../../components/parameters/runSyncParameters.yaml#/outputRecordKey" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/timeout" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/memory" - $ref: "../../components/parameters/runAndBuildParameters.yaml#/maxItems" diff --git a/sources/academy/platform/deploying_your_code/inputs_outputs.md b/sources/academy/platform/deploying_your_code/inputs_outputs.md index c0959e6764..59de298473 100644 --- a/sources/academy/platform/deploying_your_code/inputs_outputs.md +++ b/sources/academy/platform/deploying_your_code/inputs_outputs.md @@ -127,7 +127,7 @@ print(solution) ## Writing output {#writing-output} -Similarly to reading input, you can write the Actor's results either by using the Apify SDK in Node.js or by manually writing a utility function to do so. +An Actor's results generally go into its storages - a dataset, key-value store, or request queue. Similarly to reading input, you can write them either by using the Apify SDK in Node.js or by manually writing a utility function to do so. ### Writing output with the Apify SDK diff --git a/sources/academy/tutorials/api/using_apify_from_php.md b/sources/academy/tutorials/api/using_apify_from_php.md index ac584844ce..1602939f26 100644 --- a/sources/academy/tutorials/api/using_apify_from_php.md +++ b/sources/academy/tutorials/api/using_apify_from_php.md @@ -83,7 +83,7 @@ You should see information about the run, including its ID and the ID of its def ## Getting the results from dataset -Actors usually store their results in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset. +An Actor usually stores its results in a default dataset created separately for each run. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset. ```php // Replace with the run ID you from earlier