Efficient Querying

The recommended request flow

For any non-trivial workflow, run this sequence:

1. Size the segment. ?count_only=true (0 credits) — cheap way to know how big the result set is.
2. Confirm cost. ?dry_run=true (0 credits) — confirms expected rows + credits with all filters and signals applied.
3. Paginate with include_count=false. Loop page=0, 1, 2, .... The backend uses a page_size + 1 probe to set meta.has_more — much faster than re-running COUNT(*) each page.
4. Stop when meta.has_more === false.

# Step 1 — size (0 credits)
GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&count_only=true
→ meta.total_count: 12,400

# Step 2 — confirm cost (0 credits)
GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&mode=full&signals=carrier_change&page_size=100&dry_run=true
→ meta.estimated_rows: 100, meta.estimated_credits: 110.0

# Step 3 — paginate
GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&mode=full&signals=carrier_change&page_size=100&include_count=false&page=0
GET ...&page=1
GET ...&page=2
... until meta.has_more === false

Dry run

Add ?dry_run=true to any list, lookup, or batch endpoint to get the expected row count and credit cost without executing the query. The response omits data entirely and returns only a meta block with the cost breakdown.

{
  "ok": true,
  "meta": {
    "dry_run": true,
    "estimated_rows": 10,
    "estimated_credits": 11.0,
    "base_credits": 10.0,
    "signal_credits": 1.0,
    "response_tier": "advanced",
    "key_tier": "advanced",
    "credits_charged": 0,
    "phase": "internal_phase_1"
  }
}

Where base_credits is the per-row cost at the chosen mode / fields tier, signal_credits is the per-signal surcharge stacked on top (one entry per signal in signals=), and estimated_credits = base_credits + signal_credits. Use the breakdown to decide whether to trim signals before issuing the real query.

• 0 credits charged.
• Counts toward the per-key rate limit (same as count_only), so dry-run can't be abused for free unlimited queries.
• Does not count toward the daily row cap.
• Validates the query the same way a real request would — bad params, unauthorized fields, etc., all return their usual 4xx responses.
• Compatible with mode=, fields=, signals=, cf[], eb[], and every other filter.
• Works on list endpoints, /lookup, and POST /batch. Not meaningful on free endpoints (autocomplete, filter-options, credits) since their cost is already 0.
• Does not work on /export.csv; use count_only=true on the matching list endpoint instead.

When to use which feature

Anti-patterns

These are the patterns the API is designed to reject or discourage. Don't write code that does any of these.

Validate filters before you ship

Before any new query goes to production, run it once with &count_only=true and confirm the count matches your expectation. This catches overly broad geography, mistyped enum values, historical broker matching, and filter combinations that are technically valid but too wide for the job. If the count is wildly different from expectation, check the AI Agent Guide → Pitfalls and POST /v1/reports to flag a new issue.

Worked example — Clay enrichment

Goal: enrich ~5,000 California mid-market companies with their primary broker and a carrier_change flag.

# Step 1: size + cost
GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&eb[primary_broker]=true&count_only=true
→ 4,820 companies

GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&eb[primary_broker]=true
   &mode=full&fields=id,company_name,website,primary_broker,signals
   &signals=carrier_change&format=flat&page_size=500&dry_run=true
→ estimated_rows: 500, estimated_credits: 550.0

# Step 2: paginate with include_count=false
GET /v1/companies?states=CA&employee_bands=Mid-market+Accounts&eb[primary_broker]=true
   &mode=full&fields=id,company_name,website,primary_broker,signals
   &signals=carrier_change&format=flat&page_size=500&include_count=false&page=0
GET ...&page=1
... until meta.has_more === false

Total credits for ~4,820 rows: ~5,300 (4820 × 1.0 advanced + 4820 × 0.1 carrier_change ≈ 5,302). Confirmed by dry_run=true before any credits were charged.