Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

This API executes a screenshot Actor (the apify-screenshot-url integration) and returns either the Actor run metadata, the Actor's dataset items, or a key-value store output directly. The important concepts are: Actor run (the execution), outputs (dataset items vs key-value store entries), and the Apify token required to start runs. Choose the operation that both starts the run and returns the kind of output you need — calling the wrong one will start another run and duplicate work.

How the domain is organized

Executions are the central resource: each call starts an Actor run and the run produces outputs. Outputs are written to one of two places the Actor commonly uses:

  • Dataset — structured JSON items collected by the Actor (use when the Actor returns multiple JSON records about the page).
  • Key-value store — single artifacts or files (screenshots, single JSON blobs, binaries) saved under a key labeled OUTPUT or a named key.

Each operation in this API both starts a run and returns either run metadata or the run's outputs. There is no separate operation here to fetch outputs from an already-started run; pick the operation whose response contains the data you need.

Entry points — which operation to call first

Decide what the user expects to receive, then call the matching operation once:

  • If the user wants the screenshot or other single artifact saved in the key-value store, call run-sync-apify-screenshot-url. It executes the Actor, waits for completion, and returns the key-value store OUTPUT contents in body.

  • If the user wants the Actor's collected JSON items (the Actor writes a dataset), call run-sync-get-dataset-items-apify-screenshot-url. It executes the Actor, waits, and returns the dataset items in body.

  • If the user only wants run metadata (run id, status, where outputs will be written) or needs to start the run without waiting for outputs, call runs-sync-apify-screenshot-url. It returns a RunsResponseSchema in body with run details such as run id, status, timestamps, and references to dataset or key-value store IDs.

Always supply a valid Apify token in the token parameter. The body parameter must follow the Actor's input schema (the Actor expects its configured input fields there). Calling one of the "run-sync" variants starts a run — do not call multiple operations to fetch outputs for the same run unless duplicate runs are acceptable.

Common user requests and the exact operation to use

When a user asks for a concrete outcome, choose the corresponding operation and pass the Actor input in body.

  • "Take a screenshot of this URL and return the image": use run-sync-apify-screenshot-url. The response body contains the Actor's key-value store OUTPUT (the screenshot). Treat that body as the artifact to deliver.

  • "Crawl this page and return structured data about links/headings/etc.": use run-sync-get-dataset-items-apify-screenshot-url. The response body will be the dataset items — a JSON array of records the Actor produced.

  • "Start the screenshot job and give me the run id/status so I can check later": use runs-sync-apify-screenshot-url. The response body is RunsResponseSchema and typically includes run id, status, and references to dataset or key-value store where outputs will appear.

If a user request is ambiguous about which output they want (artifact vs dataset vs just run id), ask a clarifying question before calling an operation. Starting a run and then asking which outputs to fetch creates duplicate runs if an incorrect follow-up call is made.

What to inspect in responses

  • For run-sync-apify-screenshot-url, expect the useful artifact in body. Check status (top-level) to confirm success. The body may be binary or structured depending on what the Actor wrote to the key-value store.

  • For run-sync-get-dataset-items-apify-screenshot-url, body is the dataset items (JSON records). Look for the typical dataset array structure and keys that represent page data.

  • For runs-sync-apify-screenshot-url, search the returned RunsResponseSchema for fields named id, status, defaultDatasetId / datasetId, or keyValueStoreId — these locate where outputs will be written. status indicates whether the run finished, failed, or is still running.

Gotchas and practical tips

  • Do not chain operations that both start runs to obtain different outputs for the "same" job — each operation here starts a new run. If the user needs both the key-value artifact and dataset items for the same input, either call the variant that returns the desired primary output, or run the Actor once through the operation that returns metadata and then use separate fetch mechanisms (not provided here) to retrieve outputs for that run — otherwise duplicate runs will occur.

  • The run-sync variants wait for the Actor to finish. For large pages or slow resources the call can take a long time and is subject to platform-side timeouts. If the user only needs the run id or wants to poll status externally, choose runs-sync-apify-screenshot-url so the call returns run metadata quickly.

  • The response body type for the key-value output is declared as unknown. Inspect its structure at runtime: image or file artifacts may be returned as a blob-like value; JSON blobs appear as parsed JSON. Rely on the presence of status and the content of body to decide how to deliver the result to the user.

  • Always include a valid Apify token in token. Unauthorized or invalid-token responses indicate the token needs to be corrected before retrying.

  • Input shape matters. The Actor expects its configured input fields in body. If the Actor fails or returns empty outputs, verify that required input fields (URL, selector, or other Actor-specific options) were supplied in body.

Quick decision flow

When a user request arrives, use this decision flow:

  1. Does the user want a single artifact (image/file) returned directly? → call run-sync-apify-screenshot-url.
  2. Does the user want structured JSON records about the page? → call run-sync-get-dataset-items-apify-screenshot-url.
  3. Does the user only need run metadata (id/status/where outputs will appear) or wants to avoid waiting? → call runs-sync-apify-screenshot-url.

Choose one operation and pass the Actor input in body along with the token. Inspect status and the response body to determine success and where the outputs are.