Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

This actor-based Instagram-scraper API exposes three ways to run the Instagram search Actor and to get its output. The important decision is whether you need results immediately (wait for the run to finish), or you only want to start a run and return run metadata so results can be fetched later. Also distinguish the two result locations the Actor may use: the Key-value store OUTPUT (usually a single aggregated JSON) and the Dataset (an array of scraped items). Choose the operation that matches where the Actor writes results and whether you should wait for completion.

Key entities and how they relate

  • Actor run: an execution of the Instagram search scraper. A run can produce two places for output: a Key-value store (named OUTPUT by this Actor) and a Dataset (items). The run metadata typically contains the run id and references (dataset id, key-value store id) that let you locate results later.

  • Input object (the body parameter): controls what the Actor will scrape (queries, filters, limits, proxy settings, etc.) and sometimes which output target the Actor uses. Inspect this Input shape before calling so you set the query and limits the Actor expects.

  • Token: every operation requires the token argument (Apify token) at the top level of the call.

Understand that the Actor may write to either or both output locations; the operation you pick should match where the Actor writes results and whether you want to block until completion.

Entry points — which operation to call first

  • For immediate results (block until Actor finishes):

    • Use run-sync-get-dataset-items-apify-instagram-search-scraper when you expect the Actor to put results in the Dataset and you want the scraped items returned directly in the response.
    • Use run-sync-apify-instagram-search-scraper when you expect the Actor to write an aggregated result to the Key-value store under the OUTPUT key and you want that OUTPUT returned.

  • To start a run without waiting for completion (return run metadata immediately):

    • Use runs-sync-apify-instagram-search-scraper. The response includes run metadata (status, ids). Use those ids to fetch results later with operations that read Datasets or Key-value stores.

Always inspect the InputSchema for the operation you plan to call to know which fields set the search query, limits, and output behavior. Also inspect RunsResponseSchema to find where the run id, dataset id, and key-value ids appear in the run metadata.

Common user requests and the corresponding operation patterns

  • "Search Instagram for posts for hashtag X and return the items now":

    1. Populate the body with the hashtag/query and any limit or filtering fields the InputSchema exposes.
    2. Call run-sync-get-dataset-items-apify-instagram-search-scraper to receive dataset items in the response.

  • "Run a broad scrape and return a single aggregated result (counts / summary)":

    1. Ensure the InputSchema is set to cause the Actor to write aggregated output to the key-value store (if the Actor supports that).
    2. Call run-sync-apify-instagram-search-scraper to wait for completion and receive the OUTPUT value from the Key-value store in the response.

  • "Start a scrape but don’t wait — return a run id so I can check later":

    1. Set the body with the requested query and options.
    2. Call runs-sync-apify-instagram-search-scraper. The returned RunsResponseSchema will include run metadata (look for id, status, and any dataset/key-value references). Return that run id or dataset/key-value ids to the user so results can be retrieved later.

Practical steps to follow (concise)

  1. Inspect the operation’s InputSchema to find the fields for the search query, result limits, and any output-target options. Fill those in the body.
  2. Decide whether you need to wait for results:
    • If yes and results live in the dataset → call run-sync-get-dataset-items-apify-instagram-search-scraper.
    • If yes and results live in Key-value OUTPUT → call run-sync-apify-instagram-search-scraper.
    • If no (background run) → call runs-sync-apify-instagram-search-scraper and return the run id / metadata.
  3. Include token at the top level of the call.
  4. After a run-start response, inspect the returned body (or RunsResponseSchema) to find where the data is: dataset id, key-value store id, or the dataset items/OUTPUT already embedded in the response.

Non-obvious gotchas and tips

  • Dataset vs Key-value OUTPUT: the Actor may write either or both. If you call the Key-value-returning operation but the Actor writes only to the Dataset, the response will not contain the expected data. Confirm where the Actor writes by checking InputSchema (output options) or by inspecting the run metadata returned by runs-sync-apify-instagram-search-scraper.

  • Response shapes are not identical across operations: the two run-sync-* operations have body: unknown in their signatures. Don’t assume a uniform structure—open the response and locate items or OUTPUT. runs-sync-apify-instagram-search-scraper returns a typed RunsResponseSchema that typically contains run id and references; use that to find dataset/key-value ids.

  • Latency expectations: run-sync-* endpoints wait for the Actor to finish. If the configured scrape is large, the call will take correspondingly longer. Use runs-sync-* to get a run id when you want a fast response or background processing.

  • If you need to fetch results after calling runs-sync-apify-instagram-search-scraper, look for dataset id or key-value id in the returned metadata. Use the API operations that read dataset items or key-value records (search for operations that accept those ids) to retrieve results later.

  • Check for input fields that control deduplication, maxItems, and proxies. These dramatically affect run duration and the volume of results returned; set them according to user expectations.

Failure and status semantics to rely on

  • A run metadata response with a status field indicates run state (queued, running, finished, failed). If the run is not finished and you need results, return the run id so the caller can retry retrieval later. If the run is finished, results may already be present in the response (for the run-sync operations) or available at the dataset/key-value ids in the run metadata.

Use these patterns to map user intent to the correct operation: immediate items → dataset run-sync, immediate aggregated OUTPUT → key-value run-sync, start-and-return-id → runs-sync. Always inspect the InputSchema to know which body fields to set and inspect the run response to locate the dataset or key-value ids that hold the actual results.