Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

This API controls Apify Actors runs and returns their outputs or run metadata. It exposes three focused entry points: two synchronous run endpoints that start an Actor and wait for it to finish (then return either a key-value OUTPUT value or the Actor’s dataset items), and one start-only endpoint that launches a run and returns the run metadata immediately.

How the domain is organized

Think in terms of three concepts you will see in requests and responses:

  • Actor run: a single execution of an Actor. Runs produce artifacts such as a default key-value store and a default dataset. Most of what callers care about (final OUTPUT value, dataset items, run id, run status) comes from a run.
  • Key-value store OUTPUT: many Actors write a single primary result under the OUTPUT key in their default key-value store. That value can be any JSON-compatible object and is returned directly by the run-sync-apify-monitoring-reporter-dashboard operation when present.
  • Dataset items: Actors that emit structured results often write them to a dataset. The run-sync-get-dataset-items-apify-monitoring-reporter-dashboard operation returns the dataset items produced by the run.

These operations let you either: (a) start-and-wait and receive outputs immediately, or (b) start and return run metadata immediately so the caller can check status or fetch artifacts later (if other endpoints are available elsewhere).

Entry points — what to call first

Every operation requires an Apify token and a body describing what Actor to run and with which input. Choose the entry point by the output you want and whether you want to wait for completion:

  • If the user wants the Actor’s key-value OUTPUT value and wants the result returned in the same call, call run-sync-apify-monitoring-reporter-dashboard.
  • If the user wants the Actor’s dataset items and wants them returned in the same call, call run-sync-get-dataset-items-apify-monitoring-reporter-dashboard.
  • If the user wants to start a run but not wait for completion (for example to return run id / metadata immediately), call runs-sync-apify-monitoring-reporter-dashboard.

Choose the synchronous run variants when the user explicitly asks for the output in the assistant response. Choose the start-only variant when the user asks only to start a run, asks for a run id, or intends to monitor the run externally.

Typical tasks and the exact operation to use

These are the common user intents you will encounter and the corresponding operation to invoke.

  • Run an Actor and return the single primary result (key-value OUTPUT): call run-sync-apify-monitoring-reporter-dashboard with the required token and body that identifies the Actor and provides input. The call waits until the Actor finishes and the response body contains the stored OUTPUT value (or whatever the Actor wrote under that key).

  • Run an Actor and return all dataset items: call run-sync-get-dataset-items-apify-monitoring-reporter-dashboard with token and body. The call waits until the Actor completes and responds with the dataset items emitted during that run.

  • Start a run and return run metadata (do not wait): call runs-sync-apify-monitoring-reporter-dashboard with token and body. The response body follows the run metadata schema and includes identifiers and status fields for the initiated run.

When a user asks to perform multiple steps (for example: start a run, then when it finishes return dataset items), prefer the synchronous dataset or key-value operation so the run and retrieval happen in one call. The API set here does not include a separate ready-made operation to fetch a dataset or key-value by a previously obtained run id—if the user needs that kind of workflow, start the run with the synchronous endpoint that returns the desired artifact.

Inspecting responses — where IDs and outputs appear

  • All operations return a top-level status and body. Inspect body for run identifiers and artifacts.
  • runs-sync-apify-monitoring-reporter-dashboard returns a structured run object (the RunsResponseSchema). Look in the body for fields typically named id or runId (run identifier), defaultDatasetId / datasetId (dataset reference) and defaultKeyValueStoreId (key-value store reference), and status (run status). Use those fields to report back run ids and status to users.
  • The synchronous run calls (run-sync-*) return the produced artifact directly in body: the key-value version returns the OUTPUT value (whatever the Actor stored under that key), and the dataset version returns the dataset items array. Check the returned body for the expected structure rather than assuming a fixed schema.

Non-obvious behaviors and gotchas

  • Synchronous vs start-only semantics: the run-sync-* operations block until the Actor finishes and then return artifacts. runs-sync-* only starts the run and returns immediately with run metadata. If the user asks to "start and then fetch outputs when ready," prefer a single run-sync-* call that returns the outputs directly—this API collection provides the synchronous fetchers for that purpose.

  • The primary key-value result is conventionally stored under the OUTPUT key. If an Actor never writes OUTPUT, the key-value synchronous call may return null or an empty/absent value in body. Confirm the Actor’s documentation or check the returned body for presence of the result.

  • Large datasets and payload size: synchronous dataset returns include all dataset items produced during the run. For Actors that produce very large datasets, the returned body can be heavy. When the user anticipates large output or needs only a summary, offer to run the Actor with input that limits results or to request run metadata instead.

  • Errors and failure states surface in the response body: if a run fails, the synchronous operations still return and the body carries the run’s final status and error information. Do not assume a missing body means success—inspect run status and any error messages in body.

  • Required token: every operation requires the Apify token argument. Authentication is per-call; ensure the provided token has permissions to run the specified Actor and read its stores/datasets.

  • No direct "fetch by run id" operations here: this API collection focuses on starting runs (sync or async) and returning artifacts immediately. If the workflow requires starting a run and later fetching artifacts by run id, there are no explicit fetch-by-run-id operations in this set—prefer the synchronous endpoints when the user wants artifacts back in the same flow.

Practical suggestions for composing user requests

  • If the user asks simply "Run this Actor and give me the result," call the appropriate run-sync-* operation that returns the artifact the user expects (key-value OUTPUT or dataset items) and then present the body contents to the user.

  • If the user asks "Start this and give me the run id so I can check later," call runs-sync-apify-monitoring-reporter-dashboard and return the run id and status field from the response body.

  • If the Actor’s output format is uncertain, run the synchronous key-value variant first to see if an OUTPUT was produced; if that returns empty and the Actor typically writes datasets, run the dataset synchronous variant next.

Summary

Use the two run-sync-* operations when the user wants outputs returned in the same call; use runs-sync-* when the user only wants run metadata immediately. Always inspect the returned body for run ids, dataset/key-value identifiers, statuses, and error messages before reporting results back to the user. Ensure the provided token has permission to run the Actor and read its outputs.