Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

The API is focused on executing a single Apify Actor (the market expansion agent) and returning its results or run metadata. Operations differ only by what they return and whether they wait for the Actor to finish: one returns key-value store output, one returns dataset items, and one returns the run metadata for the initiated run. Each call requires an Apify token and a body that matches the Actor's InputSchema (the body must include whatever Actor identifier and input the Actor expects).

How the domain is organized

  • The central resource is an Actor run. A run can produce outputs in two common places: a key-value store (often under the key named OUTPUT) and a dataset (an array of items). Runs also expose metadata (run id, status, and references to the dataset or key-value store) that can be inspected.
  • Each operation here is a single-purpose entry point for starting the Actor and returning either: the key-value OUTPUT, the dataset items, or the run metadata. Choose the operation based on where the Actor writes its results or whether you only need the run identifier.
  • Every call requires an Apify token passed as the token parameter and a body that supplies the Actor identifier and the Actor input according to InputSchema.

Entry points — which operation to call first

  • If the user asks to "run the Actor and give me the final results," pick the operation that matches where the Actor writes results:
    • If results are written to the Actor's key-value store (common key: OUTPUT), call run-sync-apify-market-expansion-agent. It waits for the run to complete and returns the key-value store value in body.
    • If results are written to the Actor's dataset, call run-sync-get-dataset-items-apify-market-expansion-agent. It waits for completion and returns dataset items in body.
  • If the user only wants the run id, the run status, or references to where outputs will be stored (so you can fetch them later), call runs-sync-apify-market-expansion-agent. It starts the run and returns run metadata in body (look for identifiers and references to dataset or key-value store).

Choose the operation based on the Actor’s output behavior. If the user doesn’t know where the Actor writes outputs, and the user wants the actual results now, prefer the dataset variant if the Actor typically emits structured items; otherwise prefer the key-value variant.

Common tasks and how to accomplish them

Run the Actor and return final data to the user

  • If the Actor writes to the key-value store under OUTPUT, call run-sync-apify-market-expansion-agent with token and the body matching InputSchema. Inspect the returned body and return it to the user along with the status field.
  • If the Actor writes a dataset, call run-sync-get-dataset-items-apify-market-expansion-agent. The returned body contains the dataset items (usually an array). Provide those items to the user and include the status string so the user sees whether the run succeeded.

Start a run and return run metadata

  • Call runs-sync-apify-market-expansion-agent when the user asks for a run id, run status, or references to output stores. In the response body look for fields such as id, status, datasetId or keyValueStoreId (field names may vary). Use those identifiers if the user asks to fetch outputs later.

Show both metadata and results when requested

  • If a user asks for both the run id and the final results, either:
    • Use the appropriate run-sync-* variant to wait for completion and return results (this usually also includes enough run info in body for traceability), or
    • First call runs-sync-apify-market-expansion-agent to return the run id immediately, then (if the user asks to fetch results later) use the run id or returned store identifiers to obtain outputs with the appropriate fetch pattern.

Response inspection — what to look for in body

  • Always check the returned status string first. It indicates the outcome of the execution and whether the body contains final results.
  • For the key-value output variant (run-sync-apify-market-expansion-agent), the body is the value taken from the Actor's key-value store (commonly the OUTPUT key). Do not assume a particular shape; inspect the JSON structure the Actor returned.
  • For the dataset variant (run-sync-get-dataset-items-apify-market-expansion-agent), the body is typically an array of items. Look for top-level arrays or a field containing an array of items (naming varies between Actors).
  • For the run metadata variant (runs-sync-apify-market-expansion-agent), inspect body for run identifiers and references to output stores. Typical useful fields include id (or runId), status, and any dataset/key-value store IDs.

Non-obvious behaviors and gotchas

  • Token per-call: every operation requires the token parameter. Provide the correct Apify token with each request.
  • Pick the right output surface: Actors may write results to either a dataset or a key-value store; picking the wrong run-sync operation will return an empty or unexpected body. When uncertain, ask the user which Actor and what output they expect, or obtain run metadata first.
  • Output location naming varies: some Actors place final output under the key named OUTPUT, others use different keys. When a key-value fetch returns nothing, check the run metadata for other keys or use the dataset variant if the Actor emits items.
  • Schema conformity: the body must match the Actor's InputSchema. Provide the Actor identifier (name or id) and any required inputs in body exactly as the Actor expects; missing or incorrect input fields will prevent the Actor from producing the intended results.
  • Response shapes differ between runs and results: the synchronous result endpoints return the results directly in body while the runs endpoint returns metadata. Do not assume the same fields exist across these responses—inspect body for identifiers and result containers.
  • Large outputs and time: the run-sync-* endpoints wait for completion. If an Actor produces a very large dataset or runs for a long time, the synchronous call may take correspondingly longer; if the user only needs a run id, prefer the runs metadata endpoint.

Practical decision flow (summary)

  1. Does the user want the final data now or only the run id/metadata? If only metadata, use runs-sync-apify-market-expansion-agent.
  2. If final data is required now, determine where the Actor writes results (key-value store vs dataset). If dataset, use run-sync-get-dataset-items-apify-market-expansion-agent; otherwise use run-sync-apify-market-expansion-agent.
  3. Provide token and a body that conforms to InputSchema. After the call, report both the status and the returned body to the user, and inspect body for run identifiers or store references if further actions are requested.

Use these patterns to map user intents (run Actor, fetch results, start run and return id) to the single operation that accomplishes the task. The key decisions are which output surface the Actor writes to and whether the user needs immediate results or just metadata.