The API centers on executing a single Apify Actor (the social-media-leads-analyzer) and returning either the actor run metadata or the run’s produced results. The key concepts to keep in mind are Actor run, dataset items, and key-value store output (OUTPUT). Every operation requires an authentication token and an actor input payload (body), and the three operations differ only in what they return and whether they wait for the actor to finish.

How the domain is organized

• An Actor run is the unit of work. A run can produce zero or more dataset items and may write values into the actor’s key-value store (commonly under the key OUTPUT).
• Results can be consumed in two common forms: a collection of dataset items (structured, itemized output) or a single stored value in the key-value store (often used for summaries, files, or single JSON blobs). Which of these the actor produces is determined by the actor implementation and by the input you provide.
• The three operations mirror these concepts: two execute the actor and return results (one returns the key-value OUTPUT, one returns dataset items), and one starts a run and returns run-level metadata.

Entry points — which call to make first

• For immediate results when the actor is expected to finish quickly or when the user explicitly asked for results now, call one of the run-and-wait operations:
  • Use run-sync-get-dataset-items-apify-social-media-leads-analyzer when the desired output is the actor’s dataset (structured list of lead items). This returns the dataset items produced by the run.
  • Use run-sync-apify-social-media-leads-analyzer when the desired output is the actor’s key-value OUTPUT (a single file/blob/summary stored under OUTPUT).
• Use runs-sync-apify-social-media-leads-analyzer when the run may be long, when only run metadata is needed immediately, or when the caller wants a run identifier to reference later. This operation starts the run and returns run-level information (identifiers and state) rather than waiting to return full results.

Always provide the token and an appropriate body (the actor input). The same body schema drives all three operations; the difference is which output the operation returns.

Common tasks and the sequence of calls

• Get leads now (structured items): If the user asks for the list of leads in a structured form, call run-sync-get-dataset-items-apify-social-media-leads-analyzer with an input that encodes the search criteria (e.g., target accounts/pages, timeframe, filters). The response contains the dataset items for immediate consumption.

• Get a summary or single artifact: If the user expects a single summary file or a consolidated JSON (for example, a consolidated CSV or report written to the key-value store), call run-sync-apify-social-media-leads-analyzer. The response will return the value the actor stored under OUTPUT.

• Start a run and return metadata (no waiting for results): If the run might take a long time, or if only the run id/status is needed so the caller can check results later, call runs-sync-apify-social-media-leads-analyzer. Use the returned run identifier and timestamps from that response to correlate later retrievals (the actor’s run metadata is the handle for later operations outside the scope of these three operations).

Choosing between dataset items and OUTPUT (non-obvious)

• The actor may produce dataset items, an OUTPUT key in the key-value store, or both. The operation to use must match where the actor writes the data you want:

  • If the actor writes many structured records (one per lead), prefer run-sync-get-dataset-items-apify-social-media-leads-analyzer.
  • If the actor writes a single artifact (a summary JSON, aggregated CSV, or large binary) under OUTPUT, prefer run-sync-apify-social-media-leads-analyzer.

• If the actor writes both, either run-sync operation can return the part you need—but the returned payloads differ in shape. Confirm with the caller which form they want (items vs. single artifact) before selecting the operation.

Practical tips and gotchas

• Authentication is required for every call: always include the token parameter. The same token is used for all three operations.

• The three operations accept the same body input schema. Do not assume the actor will produce both dataset entries and an OUTPUT. If a run returns empty dataset items or an empty OUTPUT, the actor likely wrote to the other store or the input did not instruct it to collect data.

• run-sync-* operations wait for the actor to complete and return results. For runs that can be long-running, this can delay the response. When the user expects immediate acknowledgment or when a run may be lengthy, use runs-sync-apify-social-media-leads-analyzer to obtain run metadata instead of waiting for final results.

• Result size and payload shape differ:

  • Dataset responses are itemized JSON arrays (one object per item). Expect potentially many items.
  • OUTPUT responses are a single stored value; it may be JSON, CSV, or another blob—treat it as an opaque value that the caller asked for.

• When the user request lacks details that map to actor input (for example: which accounts to scan, date range, or limits), ask clarifying questions about those parameters before calling. The actor input drives what the run produces.

• If the caller needs a persistent reference to a run (for logging, later retrieval, or cross-checking), ensure the call that returns run-level metadata (runs-sync-apify-social-media-leads-analyzer) is used so a run identifier is available in the response.

Quick decision checklist

• User wants immediate list of leads (structured) → call run-sync-get-dataset-items-apify-social-media-leads-analyzer.
• User wants an aggregated file or summary stored as OUTPUT → call run-sync-apify-social-media-leads-analyzer.
• User wants a run id or the run may take long → call runs-sync-apify-social-media-leads-analyzer and use the returned run metadata.

Follow these patterns to match user intent to the appropriate operation and to avoid surprises from where the actor writes its results.