Skip to content

Account Aware Workflows

Jump to bottom
YuriyPei edited this page Aug 14, 2026 · 2 revisions

Account-Aware Workflows

Make web research predictable before it starts.

SearchCans is not only a SERP API and Reader API. Its Account API lets agent workflows inspect available credits and Parallel Lanes before multi-request work begins.

This enables a more production-ready pattern:

Estimate cost → check account state → cap scope or stop safely → run within observed concurrency.

Why this matters

A typical search or scraping workflow discovers budget or rate-limit problems only after work has started.

SearchCans Skills can use a job-level Account API pre-flight check to:

  • Check remaining credits before a multi-request job.
  • Estimate the maximum expected cost of planned SERP and Reader calls.
  • Reduce variable scope when the budget cannot support the full plan.
  • Stop a job before business requests are sent when work cannot safely begin.
  • Limit concurrent requests to the account’s observed Parallel Lane count.
  • Return a sanitized budget decision in the final report.

The workflow never writes raw account responses, API keys, email addresses, or tokens into reports.

What the Account API provides

Signal How Skills use it
remain Compare available credits with the estimated job cost
concurrent Limit simultaneous API calls to observed Parallel Lanes
Current key status Identify an inactive key when this state is available
Request outcome Record the budget decision without exposing account identity

Default behavior by workflow

SearchCans Deep Research

Deep Research is a multi-request workflow, so its default mode is account-aware.

Before research begins, it estimates:

Search cost + (planned Reader sources × Reader cost)

If the full plan does not fit the available balance:

  • The workflow stops if the planned search phase cannot fit.
  • Otherwise, it reduces the number of Reader sources to a safe budget.
  • A capped run never treats missing extracted sources as evidence.
  • --max-concurrency auto uses the observed Parallel Lane count.

SearchCans SERP Content Gap

A one-page SERP check stays lightweight.

For multi-page jobs, such as --page 3, the default mode can check the account and reduce the number of fetched pages to a safe scope.

SearchCans Reader SEO Audit

A standard single-URL extraction remains lightweight.

When a higher-cost Reader proxy tier is selected, the default mode can verify that enough credits are available before the extraction starts.

Account mode options

Each bundled script supports:

--account-mode auto
--account-mode off
--account-mode warn
--account-mode enforce
--account-mode cap
Mode Behavior
auto Applies the workflow’s safe default behavior
off Skips the Account API pre-flight check
warn Records budget state but continues without changing scope
enforce Stops before work when the estimated job cannot fit
cap Reduces variable scope where possible; otherwise stops safely

Cost-aware examples

Run bounded Deep Research

python scripts/deep_research.py "What is changing in the SERP API market?" \
  --subquestion "Which buyer requirements are changing?" \
  --subquestion "How do leading providers position their products?" \
  --subquestion "Which features matter for AI agent workflows?" \
  --country us \
  --language en \
  --max-sources 5 \
  --account-mode auto \
  --max-concurrency auto \
  --out research-bundle.json

Require enough credits for a multi-page SERP analysis

python scripts/serp_content_gap.py "AI search API" \
  --engine google \
  --country us \
  --language en \
  --page 3 \
  --account-mode enforce \
  --out serp-evidence.json

Check budget before using a higher-cost Reader proxy

python scripts/reader_page_audit.py "https://example.com/article" \
  --headless \
  --proxy 2 \
  --account-mode enforce \
  --out page-audit.json

Read the budget decision

Reports can include a sanitized account_guard object.

Field Meaning
estimated_credits Maximum expected cost before scope adjustment
effective_estimated_credits Expected cost after capping, if applicable
remaining_credits Available account balance at pre-flight time
concurrent_lanes Observed Parallel Lane count
effective_concurrency Concurrency selected by the workflow
budget_status Whether the planned scope is sufficient, insufficient, unavailable, or unknown
decision Whether the workflow proceeded, warned, capped scope, or blocked the job

Account state is a point-in-time signal. Other jobs using the same account can change available credits or lane availability after the pre-flight check.

Good operating practices

  • Use auto for normal work.
  • Use enforce when the requested scope must either complete in full or not start.
  • Use cap when a smaller evidence set is still useful.
  • Use warn for exploratory work where scope must remain unchanged.
  • Use off only when you deliberately do not want account-aware control.
  • Keep a meaningful source budget. More sources are not automatically better evidence.

Next steps

Useful links

SearchCans Skills

Skills

Clone this wiki locally