diff --git a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml index 6aadf96ffb..71d0a45322 100644 --- a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml +++ b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml @@ -309,14 +309,3 @@ scheduleId: type: string example: asdLZtadYvn4mBZmm -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`. - 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 d7040c3a58..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 @@ -3,7 +3,14 @@ get: - Actor tasks summary: Run task synchronously description: | - Run a specific task and return 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 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. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -27,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": @@ -63,7 +70,14 @@ 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 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. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort @@ -100,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 c98921d222..5c98e0fc8b 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,19 @@ 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. + 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). - 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 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. The Actor is started with the default options; you can override them using various URL query parameters. @@ -26,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" @@ -87,7 +92,12 @@ 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 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 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. @@ -104,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 db05c0338f..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 output 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 43bae729df..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 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. +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 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..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 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 results are 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/actors/running/input_and_output.md b/sources/platform/actors/running/input_and_output.md index 27e8c7c8ce..6b7654c3e9 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 (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. -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. 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