Quotes and runs (10 tools)
Quotes, approval and the runs they start. A run that costs credits starts only after approval.
approve_instagram_pull
Approve an Instagram pull. Approved internal clients only (Orcheo). The user’s consent to spend up to the quote’s ceiling: only call it after the user has seen quote.ceilingUsd and said yes; pass that number as acceptedCeilingUsd. The pull runs once: reuse the same idempotencyKey on a retry and it answers the same pull, never a second one. Waits up to 25 s, then answers it as it stands: follow with get_instagram_pull. Spends money (measured cost plus 20% on the monthly statement), never credits. Needs an API key of an approved client (C-047); any other caller gets not_found. Paging, provenance, availability, receipts and collector issues come back as structured fields.
- Credit cost
- May spend credits, only for data delivered
- Who can call it
- API key or Sign in with Rewalto, permission data:read
- Inputs
- pullId (string, required): The pullId from create_instagram_quote.
- acceptedCeilingUsd (number, required): The ceiling the user saw and accepted.
- idempotencyKey (string, required): A unique string for this approval (e.g. a UUID); the same one on every retry.
approve_quote
Approve a quote. Approve one open quote: this is the user’s consent to spend up to its ceiling. Only call it after the user has seen the quote’s ceiling (the most it can cost, in credits) and explicitly said yes; pass that number as confirmedCeiling. The API refuses (cost_changed) if it is not exactly the quote's ceiling, and nothing is held. For a fresh read, approving starts the run: follow it with get_run. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- May spend credits, only for data delivered
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- id (string, required): The quote id.
- confirmedCeiling (integer, required): The ceiling, in credits, that the user was shown and agreed to.
create_instagram_quote
Quote a fresh Instagram pull. Approved internal clients only (Orcheo). Prices a fresh pull: the most calls it may make, the expected cost and the ceiling it will never pass (USD, measured cost; the charge is that plus 20% on the monthly statement, never credits), valid 30 minutes. Creating it collects nothing and costs nothing. Show the user the ceiling, then approve_instagram_pull. Operations: profile and account_media (target.username), media and comments (target.shortcode), comment_replies (target.shortcode and target.commentId), hashtag_media (target.hashtag; feed recent or top), search_accounts, search_hashtags and search_reels (target.query). Needs an API key of an approved client (C-047); any other caller gets not_found. Paging, provenance, availability, receipts and collector issues come back as structured fields.
- Credit cost
- Free; saves a record
- Who can call it
- API key or Sign in with Rewalto, permission data:read
- Inputs
- operation (string, required): What to read. One of: profile, account_media, media, comments, comment_replies, hashtag_media, search_accounts, search_hashtags, search_reels.
- target (object, required)
- pages (integer, optional): Upstream pages to read (default 1).
- continue (boolean, optional): Continue where the last finished pull of this target stopped.
- surface (string, optional): account_media: feed (default) or reels. One of: posts, reels.
- sort (string, optional): comments: recent (default) or popular. One of: recent, popular.
- feed (string, optional): hashtag_media: recent (default) or top posts. One of: recent, top.
create_quote
Quote a run. Price a recipe run before anything runs: units, extras, the rate version and the ceiling. Creating a quote spends nothing. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- Free; saves a record
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- recipe (string, required): The recipe id, from the catalogue.
- units (integer, required): How many of the recipe's units.
- extras (list of object, optional): Extras by key, from the entry’s rates.
- cadence (string, optional): One of: daily, weekly, monthly.
fresh_read_quote
Quote a fresh read. Price reading a recipe fresh now, at one or more pin codes: what the recipe’s collector would read for the query at each pin, one job per pin. Creating the quote spends nothing and runs nothing. Show the user the quote’s `ceiling` (the most it can cost, in credits) and ask them to approve it; only then call approve_quote with that ceiling. Once approved, the quote id is the run id for get_run and get_run_rows. A recipe no collector runs on demand is refused (unknown_capability). Needs an API key; answers for the key’s own organisation only.
- Credit cost
- Free; saves a record
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- recipe (string, required): The recipe id, from the catalogue.
- query (string, required): A search term, or a product reference for a recipe that reads one product.
- pincodes (list of string, required): Pin codes to read at (one job each); `national` for a recipe not tied to a place.
- rowsPerPin (integer, optional): The most rows wanted at each pin (default 50); sets the quote's units.
get_instagram_pull
An Instagram quote, pull or receipt. Approved internal clients only (Orcheo). The quote, its status and, once finished, the receipt: collector, calls, measured cost, charge, rows delivered, target state, partial and truncated flags, a safe error and the build-own-collector issue of a Treg-backed pull. Poll it while running. Free. Needs an API key of an approved client (C-047); any other caller gets not_found. Paging, provenance, availability, receipts and collector issues come back as structured fields.
- Credit cost
- Free
- Who can call it
- API key or Sign in with Rewalto, permission data:read
- Inputs
- pullId (string, required): The pullId from create_instagram_quote.
get_quote
Read a quote. One quote of the key’s organisation: its total, rate version, status and expiry. Free. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- Free
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- id (string, required): The quote id.
get_run
Follow a fresh read. One fresh-read run (its id is the approved quote’s id): its status, each pin’s progress, the rows delivered and, once every pin has finished, the credits charged: for the rows delivered, never above the approved ceiling, nothing when nothing was delivered. Reading it costs nothing; the first read after the run finishes settles the charge the user already approved. Read the rows with get_run_rows. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- May spend credits, only for data delivered
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- id (string, required): The run id (the approved quote’s id).
get_run_rows
Read a fresh read’s rows. The rows a fresh-read run delivered, pin by pin, a page at a time (pass nextCursor back as cursor). Free. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- Free
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- id (string, required): The run id.
- limit (integer, optional): Rows per page (100).
- cursor (string, optional): nextCursor from the previous page.
list_runs
List fresh reads. The organisation’s fresh-read runs, newest first, a page at a time (pass page.nextCursor back as cursor): each run’s recipe, query, pins, status, rows delivered and credits charged. Listing costs nothing; a run whose pins have all finished is settled on its first read, as with get_run. Follow one with get_run or get_run_rows. Needs an API key; answers for the key’s own organisation only.
- Credit cost
- May spend credits, only for data delivered
- Who can call it
- API key or Sign in with Rewalto, permission tools:run
- Inputs
- limit (string, optional): Runs per page, 1 to 100 (20).
- cursor (string, optional): page.nextCursor from the previous page.
- since (string, optional): Only runs approved at or after this moment (ISO 8601).
