Actor output schema

Learn how to define and present the output of your Actor.

The Actor output schema builds upon the schemas for the dataset and key-value store, and defines where the output of an Actor run is stored. It allows you to define templates for URLs where users can find the output generated by your Actor. The outputs defined in the schema are used in the UI to manage how the output is displayed and are returned in the Actor run's GET endpoint for automated systems using the API.

Example

Consider a very simple example Actor that calls Actor.setValue() to save two files into the key-value store:

main.js
import { Actor } from 'apify';
// Initialize the JavaScript SDK
await Actor.init();

/**
 * Store data in key-value store
 */
await Actor.setValue('document-1.txt', 'my text data', { contentType: 'text/plain' });

await Actor.setValue(`image-1.jpeg`, imageBuffer, { contentType: 'image/jpeg' });

// Exit successfully
await Actor.exit();

To let users know that the output is stored in the key-value store, you can update the .actor/actor.json configuration like this:

.actor/actor.json
{
    "actorSpecification": 1,
    "name": "Actor Name",
    "title": "Actor Title",
    "version": "1.0.0",
    "output": {
        "actorOutputSchemaVersion": 1,
        "title": "Output schema of the Actor",
        "properties": {
            "files": {
                "type": "string",
                "title": "Files",
                "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"
            }
        }
    }
}

The schema above defines one output called files which uses the template to define a template which links to the key-value store GET keys API endpoint of the default key-value store.

This allows the UI to know that when displaying the output of a run, it needs to display data from the key-value store.

The Output tab will then display the contents of the key-value store:

Output tab in Run

And if you call the GET Run API endpoint, it will contain an output property:

"output": {
    "files": "https://api.apify.com/v2/key-value-stores/<key-value-store-id>/keys"
}

Structure

Output configuration files need to be located in the .actor folder within the Actor's root directory.

You have two choices for how to organize files within the .actor folder.

Single configuration file

.actor/actor.json
{
    "actorSpecification": 1,
    "name": "files-scraper",
    "title": "Files scraper",
    "version": "1.0.0",
    "output": {
        "actorOutputSchemaVersion": 1,
        "title": "Output schema of the files scraper",
        "properties": /* define your outputs here */
    }
}

Separate configuration files

.actor/actor.json
{
    "actorSpecification": 1,
    "name": "files-scraper",
    "title": "Files scraper",
    "version": "1.0.0",
    "output": "./output_schema.json"
}

.actor/output_schema.json
{
        "actorOutputSchemaVersion": 1,
        "title": "Output schema of the files scraper",
        "properties": /* define your outputs here */
    }

Choose the method that best suits your configuration.

Output schema structure definitions

The key-value store schema defines the collections of keys and their properties. It allows you to organize and validate data stored by the Actor, making it easier to manage and retrieve specific records.

Key-value store schema object definition

Property	Type	Required	Description
`actorOutputSchemaVersion`	integer	true	Specifies the version of output schema structure document. Currently only version 1 is available.
`title`	string	true	Title of the schema
`description`	string	false	Description of the schema
`properties`	Object	true	An object where each key is an output ID and its value is an output object definition (see below).

Output object definition

Property	Type	Required	Description
`title`	string	true	The output's title, shown in the run's output tab if there are multiple outputs and in API as key for the generated output URL.
`description`	string	false	A description of the output. Only used when reading the schema (useful for LLMs)
`template`	string	true	Defines a template which will be translated into output URL. The template can use variables (see below)

Available template variables

Variable	Type	Description
`links`	object	Contains quick links to most commonly used URLs
`links.publicRunUrl`	string	Public run url in format `https://console.apify.com/view/runs/:runId`
`links.consoleRunUrl`	string	Console run url in format `https://console.apify.com/actors/runs/:runId`
`links.apiRunUrl`	string	API run url in format `https://api.apify.com/v2/actor-runs/:runId`
`links.apiDefaultDatasetUrl`	string	API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId`
`links.apiDefaultKeyValueStoreUrl`	string	API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId`
`links.containerRunUrl`	string	URL of a webserver running inside the run in format `https://<containerId>.runs.apify.net/`
`run`	object	Contains information about the run same as it is returned from the `GET Run` API endpoint
`run.defaultDatasetId`	string	ID of the default dataset
`run.defaultKeyValueStoreId`	string	ID of the default key-value store

Advanced examples

The output schema and its template property allow a lot of flexibility to support a wide array of Actors. Here are some examples to help you get started.

Linking dataset views and key value store collections

This example shows a schema definition for a basic social media scraper. The scraper downloads post data into the dataset, and video and subtitle files into the key-value store.

If we correctly define views and collection in dataset_schema.json and key_value_store_schema.json, we can then use them in output schema like this:

.actor/output_schema.json
{
    "actorOutputSchemaVersion": 1,
    "title": "Output schema of Social media scraper",
    "properties": {
        "overview": {
            "type": "string",
            "title": "Overview 🔎",
            "template": "{{links.apiDefaultDatasetUrl}}/items?view=overview"
        },
        "posts": {
            "type": "string",
            "title": "Posts ✉️",
            "template": "{{links.apiDefaultDatasetUrl}}/items?view=posts"
        },
        "author": {
            "type": "string",
            "title": "Authors 🧑‍🎤",
            "template": "{{links.apiDefaultDatasetUrl}}/items?view=author"
        },
        "music": {
            "type": "string",
            "title": "Music 🎶",
            "template": "{{links.apiDefaultDatasetUrl}}/items?view=music"
        },
        "video": {
            "type": "string",
            "title": "Video 🎞️",
            "template": "{{links.apiDefaultDatasetUrl}}/items?view=video"
        },
        "subtitleFiles": {
            "type": "string",
            "title": "Subtitle files",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys?collection=subtitles"
        },
        "videoFiles": {
            "type": "string",
            "title": "Video files",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys?collection=videos"
        }
    }
}

The schema above defines five dataset outputs and two key-value store outputs. The dataset outputs link to specific views defined in dataset_schema.json, and the key-value store outputs use similar logic to target a specific collection defined in key_value_store_schema.json.

When a user runs the Actor in the Console, the UI will look like this:

Video files in Output tab

Using container URL to display chat client

In this example, we have an Actor that internally runs a web server that allows users to connect to an LLM and chat with it. The conversation history is then stored in the dataset.

.actor/output_schema.json
{
    "actorOutputSchemaVersion": 1,

    "title": "Chat client output",
    "description": "Chat client provides interactive view to converse with LLM and chat history in dataset",
    "type": "object",

    "properties": {
        "clientUrl": {
            "type": "string",
            "title": "Chat client",
            "template": "{{run.containerUrl}}"
        },
        "chatHistory": {
            "type": "string",
            "title": "Conversation history",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
        }
    }
}

In the schema above we have two outputs. The clientUrl output will return a link to the web server running inside the run. The chatHistory links to the default dataset and contains the history of the whole conversation, with each message as a separate item.

When the run in the Console, the user will then see this:

Chat in Output tab

Custom html as run output

This example shows an output schema of an Actor that runs Cypress tests. When it finishes, it generates an HTML report and stores it in the key-value store. We can then link to this file and show it as an output like this:

.actor/output_schema.json
{
    "actorOutputSchemaVersion": 1,

    "title": "Cypress test report output",
    "description": "Test report from Cypress",
    "type": "object",

    "properties": {
        "reportUrl": {
            "type": "string",
            "title": "HTML Report",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/records/report.html"
        }
    }
}

The reportUrl in this case links directly to the key-value store record stored in the default key-value store.

When the output run is finished, the record will be displayed in an <iframe> element in the Console like this:

HTML report in Output tab

Actor with no output

If your Actor has no output (for example, if it's an integration that performs an action and exits), it can be confusing for users, as they will see the empty Output tab and think the Actor did not work.

You can force the Console to "know" that the Actor has no output by not defining any outputs in the output schema:

.actor/output_schema.json
{
    "actorOutputSchemaVersion": 1,

    "title": "Send mail output",
    "description": "Send mail Actor does not generate any output.",
    "type": "object",

    "properties": {}
}

When you run an Actor with an output schema defined with no properties, the Console will default to showing the Log tab.

Actor output schema

Example​

Structure​

Single configuration file​

Separate configuration files​

Output schema structure definitions​

Key-value store schema object definition​

Output object definition​

Available template variables​

Advanced examples​

Linking dataset views and key value store collections​

Using container URL to display chat client​

Custom html as run output​

Actor with no output​