Account‐Aware Workflows

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 normal search or scraping workflow often 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

The Account API can provide the signals needed for request control:

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

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.

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.

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.

Useful fields include:

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 the available balance 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 observing the account state is useful but scope should 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

• Getting Started
• Choose a Workflow
• Deep Research Playbook
• Troubleshooting

Useful links

• SearchCans Account API documentation
• Rate Limits and Parallel Lanes
• SearchCans API documentation
• GitHub repository