These endpoints run the Apify Instagram Scraper actor and return either the actor run metadata, the actor's dataset items, or the actor's key‑value OUTPUT. All three require a valid Apify token and the actor input in body (the actor’s InputSchema controls what you can request: target username, hashtag, limits, date ranges, etc.). Choose the operation by what you need back and whether you want the call to wait for the actor to finish.

Key entities and how they relate

• Actor run: an execution of the Instagram scraper. A run has metadata (id, status, timestamps) and produces outputs in two common places: a Dataset (structured items) and a Key-Value store (arbitrary artifacts, commonly a single OUTPUT JSON).
• Dataset items: the actor’s structured results (posts, comments, metadata) presented as an array of items. Use these when the actor emits rows/records you want to inspect or return to the user.
• Key-value OUTPUT: many Apify actors write a primary result under the key named OUTPUT. This can be a JSON object or other artifact (HTML, CSV). Use this when the actor documents a single primary output document rather than a list of items.

The three operations map directly to these entities:

• run-sync-apify-instagram-scraper — executes the actor, waits for completion, and returns the Key-Value OUTPUT from the run.
• run-sync-get-dataset-items-apify-instagram-scraper — executes the actor, waits for completion, and returns the run’s Dataset items.
• runs-sync-apify-instagram-scraper — starts an actor run and returns information about the initiated run (metadata). It does not return the run’s dataset or OUTPUT content.

Entry points — which operation to call first

Pick the operation that yields the shape you will use immediately:

• If the user asked for a list of posts, recent media, or records: call run-sync-get-dataset-items-apify-instagram-scraper and pass the actor input that selects the profile/hashtag and any limits (e.g., limit, maxPosts). The response body will contain the dataset items.
• If the user asked for a single JSON summary, exported file, or the actor’s primary artifact: call run-sync-apify-instagram-scraper to get the Key-Value OUTPUT from the run.
• If the user asked only to start a scrape and return run information (for later checking or asynchronous workflows): call runs-sync-apify-instagram-scraper. Use the returned run metadata (id, status) to reference the run in follow-up actions or external Apify operations.

Because the actor input drives what gets scraped, populate body with the actor’s input fields for target selection (username, hashtag, location, date filters, and any limit options). If in doubt, include the target identifier (username or hashtag) plus an explicit limit so the run completes predictably.

Common tasks and the exact operation to use

• "Give me the latest N posts from @username as JSON": call run-sync-get-dataset-items-apify-instagram-scraper with body containing the target username and a posts limit. Return the array in the response.
• "Fetch the actor’s summarized output (single JSON)": call run-sync-apify-instagram-scraper and return the response body (this reads the run’s key-value OUTPUT).
• "Start a scrape and tell me the run id/status so I can check later": call runs-sync-apify-instagram-scraper and return the run metadata (look for run id and status fields in RunsResponseSchema).
• "Run a scrape and save the results elsewhere or process them now": prefer the dataset-items variant when you need structured rows to transform. Prefer the key-value OUTPUT variant when the actor produces a single summary document or file.

Non-obvious behaviors and important gotchas

• Synchronous vs. asynchronous semantics: the two run-sync-* operations wait for the actor run to finish and then return results in the HTTP response. That makes them convenient for small, quick scrapes but susceptible to long waits or timeouts for large jobs. Use the runs-sync-* operation to start a run when the user expects asynchronous processing or when run duration may be long.

• Dataset vs Key-Value differences: the dataset can contain many rows; the key-value OUTPUT is commonly a single JSON object. The actor may populate one or both; choose the operation that matches where the actor writes the data. If unsure which the actor uses for a particular input, request both behaviors in separate calls or inspect the actor’s documentation/input schema.

• Dependence on actor input correctness: the body must match the actor’s InputSchema. If required fields (target username, mode, or auth options) are missing or misspelled, the run may complete with no items or an error status. When returning results to users, surface run status or any error messages in the response so callers can see that the actor executed but produced no data.

• Output size and run duration: large scrapes produce many dataset items and take longer. For very large requests, prefer starting the run with runs-sync-apify-instagram-scraper and then retrieve results through a dedicated dataset retrieval flow (not exposed here) or request the user narrow the scope (limit, date range).

• token is mandatory: every call requires a valid Apify token supplied in the token parameter. The token determines access to the actor and its runs; invalid or insufficient-scope tokens will cause authentication or authorization errors.

• Response content varies by operation: expect structured arrays from the dataset-items operation and a single artifact for the key-value OUTPUT operation. The runs-sync response contains run metadata (look for run id, status, start/finish timestamps) and does not include dataset items or OUTPUT content.

Practical checklist for typical requests

1. Decide desired output shape: dataset rows (multiple items) vs single artifact (OUTPUT) vs just run metadata.
2. Populate body with the actor’s input fields that select target(s) and set limits to keep runs predictable.
3. Include a valid token in every call.
4. Use run-sync-get-dataset-items-apify-instagram-scraper for structured results, run-sync-apify-instagram-scraper for the single OUTPUT, and runs-sync-apify-instagram-scraper to start a run and return metadata only.

Following these patterns ensures the call returns the data shape the user expects and avoids waiting unnecessarily for long-running scrapes.