The Actor API runs the Apify Instagram hashtag scraper and returns either the Actor run record, the dataset items produced by a run, or the Key-Value store OUTPUT directly. The three operations expose two different run modes: a non-blocking start that returns run metadata, and two blocking calls that wait for the Actor to finish and then return a specific output location. Choose the operation that matches the output you need before starting the run—there is no single call here that atomically returns both dataset items and key-value OUTPUT for the same run.

How the domain is organized

• The central concept is an Actor run. You start an Actor with an InputSchema payload that configures what the scraper does (hashtags, limits, date ranges, proxies, etc.). Each invocation creates a run.
• Actor runs produce two different kinds of outputs commonly used by callers: a dataset (an ordered collection of items) and a Key-Value store entry named OUTPUT. The three operations map to starting a run or to starting-and-waiting while returning one of those outputs.
• Every operation requires an Apify token and a body that conforms to the Actor's InputSchema. Inspect the operation's body type to learn the exact fields the Actor expects (which fields are required, optional controls for limits and proxies, and any mode switches that select dataset vs key-value output).

Entry points — which operation to call first

• If the user only wants to start the Actor and receive run metadata (run id, start time, initial status), call the non-blocking start operation that returns run information. Use this when the user intends to monitor or reference the run elsewhere rather than waiting for results.

• If the user asks for scraped items (the Actor writes results to a dataset and the user wants those items), call the synchronous dataset operation that waits for the run to finish and returns the dataset items in the response body.

• If the user asks for the Actor's OUTPUT (the Key-Value store object the Actor writes), call the synchronous key-value operation that waits for completion and returns the OUTPUT content in the response body.

Choose the operation based on the output location you need: run metadata, dataset items, or key-value OUTPUT.

Common tasks and the exact operation to use

Below are the typical user intents and which operation accomplishes each. For each, set the Apify token and supply a body that matches the Actor's InputSchema (set hashtags, limits, proxies, and any mode flags there). Inspect the body schema to confirm property names and required values.

• "Start a run and return the run record (run id/status)."

  • Use the non-blocking start operation that returns a RunsResponseSchema. This gives a run id and metadata immediately; it does not wait for completion.

• "Run the scraper and return the dataset items (the list of scraped posts)."

  • Use the synchronous dataset operation that waits until the Actor finishes and returns dataset items in the response body.

• "Run the scraper and return the Key-Value store OUTPUT (single JSON payload)."

  • Use the synchronous key-value operation that waits until finish and returns the OUTPUT content in the response body.

Note: the synchronous operations block until the Actor run finishes and then return the selected output. There is no built-in operation here to get both dataset items and key-value OUTPUT from a single run in one call; if both outputs are required, plan ahead which output to request or run separate executions (each run creates independent results).

Response shapes and what to inspect

• All responses include a status field and a body field. status signals high-level outcome (success, error, etc.); body contains the returned payload.
• For the non-blocking start operation, body follows RunsResponseSchema and typically contains a run id and metadata. Use the run id when the user needs to reference this run in external workflows or logs.
• For the synchronous dataset operation, body contains the dataset items (an array of scraped objects). Expect the items to be the scraped posts or records the Actor collects.
• For the synchronous key-value operation, body contains the content stored under the run's Key-Value OUTPUT key (often a single JSON object or array with aggregated results).
• If the Actor fails, status and body will include error information emitted by the Actor. Check both fields to determine whether the run succeeded and whether the returned body contains usable data.

Gotchas and operational quirks

• Pick the output you need before invoking: the API offers synchronous returns for one output type at a time (dataset items or Key-Value OUTPUT) and a non-blocking start that returns only run metadata. There is no combined synchronous endpoint here that returns both dataset and key-value payloads for the same run.

• Synchronous calls wait for the Actor to finish. Long scrapes may take significant time; prefer the non-blocking start if the user does not want to wait or the scrape may be long-running.

• Each invocation creates a new Actor run. Repeated calls with the same body create separate runs and separate outputs. If deduplication or reusing results is required, coordinate externally (store returned run ids or outputs outside the Actor outputs).

• The InputSchema controls behavior. Some Actors expose switches that change where results are written (dataset vs key-value) or limit the result volume. Confirm these switches in the body type so the run produces results in the location the user expects.

• Authentication is required: every call requires an Apify token parameter. Ensure the provided token has permission to start the Actor and read its outputs.

• Resource and cost implications: each run executes the Actor runtime and consumes resources. For large or frequent requests, prefer constrained limits in the InputSchema (result limits, date ranges) to avoid long-running executions.

Quick decision checklist

Before calling an operation, verify in this order:

1. Does the user want run metadata only, or actual scraped data? If metadata only, use the non-blocking start.
2. If scraped data is required, decide which output: dataset items or Key-Value OUTPUT? Use the corresponding synchronous call.
3. Inspect the operation's body schema to confirm the exact fields to supply (hashtags, limits, proxies, mode flags).
4. Provide a valid Apify token.

Following that checklist ensures the run produces data in the location the user expects and avoids starting unnecessary runs.