Apify

HOW in lib/apify.py. Docs: docs.apify.com (OpenAPI). Actor model — discover → run → read dataset.

Auth & config

• BYOK-only — Apify isn't resold on managed credits. Each workspace connects its own Apify token in Integrations; without one every Apify call returns no_key. hyreflow charges 0 credits; Apify bills you directly. Connecting your own token needs the Essential plan or above.
• Base URL: https://api.apify.com/v2 · Auth: Authorization: Bearer <token> (env APIFY_API_KEY; never hardcode).
• actorId is username/name; the client converts it to username~name for paths.

Operations (the canonical flow)

1. list_store_actors(search=...) — find an actor when you don't know its id (pick high rating/usage; for LinkedIn posts prefer supreme_coder/linkedin-post).
2. get_actor_input_schema(actor_id) — required/optional inputs before running.
3. run_actor_sync(actor_id, run_input) — run + return dataset items in one call (default).
4. Async: run_actor(...) → get_run(run_id) (poll status + defaultDatasetId) → get_dataset_items(dataset_id).

Guardrails

• Actor runs cost compute on your own Apify account and some are rental-priced — pilot small (low maxItems) before scaling. Read-only sourcing tool (no outreach side-effects).
• Sites requiring login: prefer a vetted actor; avoid scraping behind auth without permission.

Handoff

Sourcing/scraping layer: e.g. scrape LinkedIn posts/engagers or profiles → structured rows → enrichment (emails/phones) → ATS/sequencer.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• Find the actor first: if you don't know the actor ID, search the store; the #1 result by quality is usually the right pick (ranked by rating x review count x runs x 30-day success). Prefer vetted, high-usage, successRate30d >= 95% actors. For LinkedIn posts -> supreme_coder/linkedin-post; for post reactions/engagers -> harvestapi/linkedin-post-reactions.
• actorId = username/name (note: our adapter also accepts the username~name form per Apify's API).
• Inspect the input schema before running - required/optional fields vary per actor and the wrapper fields can differ from the actor-page docs.
• Default to a sync run for one-call results; use async + poll only for long/non-blocking jobs.
• Validate payload with a tiny run (low maxItems) before scaling.

Callable surface — lib/apify.py

Import: from lib.apify import Apify → instantiate Apify() (reads key from env). Base: https://api.apify.com/v2. Generic passthrough: request(method, path, *, params, json).

• get_actor_default_build(actor_id: str) -> Any — GET /acts/{actor}/builds/default — the full default build (inputSchema, readme, usage). FREE.
• get_actor_input_schema(actor_id: str) -> Any — Inspect an actor's input fields before running (FREE — read only).
• get_dataset_items(dataset_id: str, *, limit: int | None = None, offset: int | None = None, **params) -> Any — GET /datasets/{datasetId}/items — fetch an actor run's output.
• get_limits() -> Any — GET /users/me/limits — monthly usage cycle + limits + current usage. Free. Reports the CALLER's own Apify budget: remaining monthly USD = data.limits.maxMonthlyUsageUsd - data.current.monthlyUsageUsd (Apify is usage-metered in USD, not a credit pool). Apify is BYOK-only, so there is no Hyreflow-managed Apify account and no internal balance poll behind this — it reads the workspace's own account.
• get_run(run_id: str) -> Any — GET /actor-runs/{runId} — run status (look at data.status + data.defaultDatasetId).
• get_user() -> Any — GET /users/me — authenticated account (plan/usage). Free, no args — the BYOK key-verification probe (GET /store is public and would NOT validate the token).
• list_store_actors(*, search: str | None = None, limit: int = 25, **params) -> Any — GET /store — search the Apify actor store. Use first when you don't know the actorId.
• run_actor(actor_id: str, run_input: dict | None = None, **params) -> Any — POST /acts/{actor}/runs — start an async run. Poll get_run, then get_dataset_items.
• run_actor_sync(actor_id: str, run_input: dict | None = None, **params) -> Any — POST /acts/{actor}/run-sync-get-dataset-items — run an actor and return dataset items in one blocking call. Best default when you want results immediately.