Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

This API executes a single Apify Actor that gathers Instagram hashtag statistics and returns either the Actor run metadata, the Actor’s dataset items, or the Actor’s key-value OUTPUT. The three operations are variants of the same workflow: start the Actor with a given input (the body), authenticate with the token, and receive either the run record, dataset items, or the key-value OUTPUT. Understand that the domain here is: Actor run → produced artifacts (dataset, key-value store) → data you present to the user.

Key concepts and how they relate

  • The body argument is the Actor input: populate it with the hashtag(s), limits, time ranges, or other options the Actor expects. The input schema is the authoritative place to learn which fields are required for a particular run.
  • A single Actor run can produce two kinds of artifacts you typically care about: a dataset (multiple structured items) and a key-value store (single JSON blobs, often under OUTPUT). Which artifact you need determines which operation to call.
  • Every call must include a valid token with permissions to start the Actor and read its artifacts.
  • The three operations differ only in what they return and whether they wait for the Actor to finish:
    • runs-sync-apify-instagram-hashtag-stats: starts the Actor and returns the run record (run metadata) about the initiated run. Use this when you only need the run id/status or want to inspect produced artifact identifiers without waiting for completion.
    • run-sync-get-dataset-items-apify-instagram-hashtag-stats: starts the Actor and waits for it to finish, then returns the Actor’s dataset items in body. Use this when you want the structured items the Actor writes to its dataset.
    • run-sync-apify-instagram-hashtag-stats: starts the Actor and waits for it to finish, then returns the key-value store OUTPUT object in body. Use this when the Actor writes an aggregated JSON under OUTPUT and you want that object directly.

What to call first (entry points)

Decide what the user wants to see first: a run record, dataset items, or an OUTPUT object. That determines which operation to call directly—there is no separate step required to discover an actor id or dataset id beforehand because the operation itself starts the Actor.

  • If the user asks "run this Actor and give me structured rows/results", call run-sync-get-dataset-items-apify-instagram-hashtag-stats with the Actor input in body.
  • If the user asks "run the Actor and return the aggregated JSON/statistics", call run-sync-apify-instagram-hashtag-stats (the key-value OUTPUT variant) with the Actor input in body.
  • If the user wants to start the run and receive run metadata (run id, status, artifact ids) immediately so they can be inspected or polled later, call runs-sync-apify-instagram-hashtag-stats.

There is no separate prerequisite call to list actors or find dataset IDs: these operations initiate runs for the specific Instagram-hashtag-stats Actor and return either the artifacts or the run metadata that identifies artifacts.

Typical user requests and how to fulfill them

  1. "Get the latest dataset items for #sunset and summarize engagement."

    • Build the Actor input body with the hashtag and any limits/time filters the Actor supports. Inspect the input schema fields to know exact parameter names.
    • Call run-sync-get-dataset-items-apify-instagram-hashtag-stats with token and that body.
    • Extract the dataset items from the operation response body (the operation returns an object with status and body; the items are inside body).
    • Summarize or filter those items to answer the user’s question.

  2. "Produce a single aggregated JSON report for #travel and return it."

    • Populate body with the hashtag and aggregation options if available.
    • Call run-sync-apify-instagram-hashtag-stats.
    • The response body will contain the Actor’s key-value store OUTPUT (the aggregated JSON). Return that object to the user or extract fields you need.

  3. "Start a run for several hashtags and give me run IDs so I can check them later."

    • For each requested input, call runs-sync-apify-instagram-hashtag-stats.
    • Collect the returned run record fields (look for id, status, and any artifact identifiers such as datasetId or keyValueStoreId) and present them to the user so they can be referenced later.

Response shape and what to inspect

Each operation returns an object with status and body. Do not assume the same structure inside body across operations:

  • For the dataset-items operation, body holds the dataset items array (the structured rows the Actor produced).
  • For the OUTPUT operation, body holds the key-value OUTPUT object (often a single JSON document with aggregated stats).
  • For the runs operation, body is the run metadata (look inside it for id, status, and any artifact IDs or links such as datasetId or keyValueStoreId). Use those fields to explain what artifacts were created.

Always inspect the body fields to determine whether the Actor produced data or whether arrays/objects are empty.

Non-obvious patterns and gotchas

  • Choose the operation by the artifact you need, not by whether you want the run started. The two "run-sync" variants wait for completion and return artifacts; the runs-sync variant returns the run record immediately without artifact contents. Confusing these will cause you to either block waiting for a run when you only needed the id, or to miss artifacts when you only started the run metadata.

  • The body you pass is the Actor input. The exact field names and required parameters are defined in the input schema. Inspect the input schema before invoking: missing required input fields will cause the Actor run to fail or produce no data. The operations do not accept separate parameters for hashtags or limits outside of body.

  • Long-running runs: the run-sync variants wait until the Actor finishes. Expect the call to take however long the Actor needs; plan accordingly when the user asks for quick answers. If you only want to kick off work and report back later, use the runs-sync variant so you get the run id immediately.

  • Empty artifacts: a successful run can still produce an empty dataset or no OUTPUT. Check for an empty array in dataset responses or a missing/null OUTPUT object and surface that to the user rather than assuming data exists.

  • Authentication matters every call: include token on every request. The token must have the rights to start the Actor and read its artifacts.

  • Response extraction: the operations return { status, body }. Inspect status for high-level result info, but read body for the actual data you need to present. Don’t assume the shape—confirm whether body is an array (dataset items), an object (OUTPUT), or a run record.

Practical tips

  • When the user’s request is to compare or aggregate multiple hashtags, run the Actor separately for each hashtag input and then combine results. Each run yields its own dataset/OUTPUT.
  • If the user asks for the run id or artifact ids for later retrieval, return the run record fields from runs-sync-apify-instagram-hashtag-stats so they can reference those identifiers.
  • If you need a concise summary rather than raw items, prefer the key-value OUTPUT variant if the Actor produces an aggregated report; otherwise request dataset items and compute the summary yourself.

Use the operation whose return value matches the artifact you need: dataset items for row-level data, key-value OUTPUT for single aggregated JSON, or runs metadata when you only need to start the run and record its id/status.